Ir para o conteúdo

Envio de mensagens em massa#

/v1/broadcast

Use o método broadcast para enviar mensagens em massa para seus contatos. Suporta o envio de mensagens de texto, bem como mensagens com imagens, vídeo, áudio e documentos. O número de destinatários não é limitado.

Condições de entrega do envio em massa#

As mensagens serào entregues se as seguintes condições forem atendidas:

  • O número de telefone da conta a partir da qual o envio é realizado está registrado nos contatos no telefone do destinatário;
  • O destinatário da mensagem deve primeiro receber pelo menos uma mensagem da conta de envio.

Limitações#

Ao enviar mensagens em massa, as seguintes restrições são definidas:

  • Tamanho máximo da imagem: 1000x1000 px
  • O comprimento mínimo do texto de envio: 10 caracteres
  • Comprimento máximo do texto de envio: 2000 caracteres
  • Número mínimo de contatos de destino: 2 contatos
  • Número máximo de contatos de destino: ILIMITADO

Seleção de destinatários de envio#

É possível definir de forma flexível os destinatários da correspondência:

  • Enviar mensagens para todos os contatos (não especifique nenhum dos parâmetros: to,period, active);
  • Enviar mensagens para lista de contatos (use o parâmetro to);
  • Enviar mensagens aos contatos cadastrados no período especificado (usar o parâmetro period);
  • Enviar mensagens aos contatos ativos no período especificado (use o parâmetro active).

Os parâmetros perido eactive podem ser combinados entre si. O parâmetro to não pode ser combinado com nenhum outro parâmetro e é aplicado separadamente.

Requisição#

Para enviar mensagens em massa, você precisa realizar uma requisição em:

POST https://api.green-api.com/v1/broadcast

{
    "name": "broadcast-name",
    "to": [
        {"wa_id": "whatsapp-id-1"},
        {"wa_id": "whatsapp-id-2"},
        {"wa_id": "whatsapp-id-3"}
    ],
    "period": {
        "from": "registration-period-from",
        "to": "registration-period-to"
    },
    "active": {
        "from": "contact-active-from",
        "to": "contact-active-to"
    },

    "type": "text" | "image" | "video" | "audio" | "document",

    "text": {
        "body": "your-text-message-content"
    },

    "image": {
        "id": "your-media-id",
        "caption": "your-image-caption"
    },

    "image": {
        "link": "http(s)://the-url",
        "caption": "your-image-caption"
    },

    "video": {
        "id": "your-media-id"  
    },    

    "video": {
        "link": "http(s)://the-url"
    },

    "audio": {
        "id": "your-media-id"  
    },      

    "audio": {
        "link": "http(s)://the-url"
    },

    "document": {
        "id": "your-media-id",
    },

    "document": {
        "link": "http(s)://the-url",
    },

    "startAt": "date-to-start-broadcast"
}

O corpo da solicitação é mostrado como um exemplo. O exemplo lista todas as opções possíveis para enviar dados de mídia. Um corpo de solicitação válido pode conter apenas um objeto de mídia ou apenas um objeto de mensagem de texto.

Parâmetros de Solicitação#

Parâmetro Tipo Obrigatório Descrição
name string Sim Nome para definição do Envio em Massa
to array Não Array com a seleção de contatos para envio. Se o parâmetro for especificado, apenas os contatos do array receberão a mensagem. O número mínimo de contatos são 2 e máximo ILIMITADO.
period object Não Seleção pelo período de inscrição dos contatos. Se o parâmetro for especificado, apenas os contatos registrados no intervalo de datas especificado receberão as mensagens.
active object Não Seleção pelo período de atividade do contato. Se o parâmetro for especificado, a lista de mensagens será recebida apenas por contatos ativos no intervalo de datas especificado.
type string Não O tipo de mensagem a ser enviada. Pode aceitar os valores: text,image, video,audio, document. Ao enviar uma mensagem de texto, o parâmetro é opcional. Valor padrão: text.
text object Sim, se "type": "text" Objeto de mensagem de texto. Para obter detalhes, consulte Enviando mensagens de texto
image object Sim, se "type": "image" Objeto de dados de imagem. Para obter detalhes, consulte Enviando mensagens com mídia
video object Sim, se "type": "video" Objeto de dados de video. Para obter detalhes, consulte Enviando mensagens com mídia
audio object Sim, se "type": "audio" Objeto de dados de áudio. Para obter detalhes, consulte Enviando mensagens com mídia
document object Sim, se "type": "document" Objeto com dados do documento. Para obter detalhes, consulte Enviando mensagens com mídia
startAt date Não Data de início do envio. Se o valor não for especificado, o envio começará imediatamente

Array to

Parâmetro Tipo Obrigatório Descrição
wa_id string Sim ID do Contato. O número mínimo de elementos em uma array é dois. O valor máximo não é limitado.

Objeto period

Parâmetro Tipo Obrigatório Descrição
from date Sim O limite inferior de seleção pela data de inscrição na lista de contatos
to date Sim O limite superior de seleção pela data de inscrição na lista de contatos

Objeto active

Parâmetro Tipo Obrigatório Descrição
from date Sim O limite inferior de seleção pela data de atividade na lista de contatos
to date Sim O limite superior de seleção pela data de atividade na lista de contatos

Objeto text

Parâmetro Tipo Obrigatório Descrição
body string Sim Mensagem de texto. Pode conter vários URLs e formatação. O comprimento mínimo do texto da mensagem é de 10 caracteres, o comprimento máximo é de 2.000 caracteres. Emoji são suportados 😃.

Exemplo de Solicitação#

Enviando mensagem em massa para todos os contatos:

{
    "name": "Broadcast from Green-API",
    "type": "text",
    "text": {
        "body": "I use Green-API to send this broadcast to you!"
    }
}

Enviando uma mensagem massa para uma lista de contatos:

{
    "name": "Broadcast from Green-API",
    "to": [
        {"wa_id": "5521988897878"},
        {"wa_id": "5521988897879"},
        {"wa_id": "5521988897890"}
    ],    
    "type": "text",
    "text": {
        "body": "I use Green-API to send this broadcast to you!"
    }
}

Envio de mensagem em massa aos contatos cadastrados em janeiro de 2020:

{
    "name": "Broadcast from Green-API",
    "period": {
        "from": "2020-01-01 00:00:00",
        "to": "2020-01-31 23:59:59"
    },   
    "type": "text",
    "text": {
        "body": "I use Green-API to send this broadcast to you!"
    }
}

Envio a todos os contatos com uma imagem e uma descrição abaixo da imagem. No exemplo, o arquivo de imagem foi carregado anteriormente para o armazenamento em nuvem media e o ID do arquivo erabca567ba-0bd7-4211-8792-0c123fbd2716:

{
    "name": "Broadcast from Green-API",
    "type":  "image",
    "image": {
        "id": "bca567ba-0bd7-4211-8792-0c123fbd2716",
        "caption": "I use Green-API to send this broadcast to you!"
    }
}

Resposta#

Em uma resposta bem-sucedida, o código HTTP 201 é retornado

Campo Tipo Descrição
broadcast array Array com os identificadores das campanhas criadas

Array broadcast

Campo Tipo Descrição
id string ID da Lista de Envio Criada

Exemplo de Resposta#

201 Created

{
    "broadcast": [
        {
            "id": "5f205403eb8c561bd4a51f27"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.0.1"
    }
}

Erros#

Para obter uma lista de erros comuns a todos os métodos, consulte a seção Erros padrão.

Em caso de erro, o código HTTP 400 é retornado com uma descrição detalhada do erro no corpo da resposta.

Exemplo de Resposta de Erro#

{
    "errors": [
        {
            "code": 81,
            "details": "Failed to create broadcast",
            "title": "Falha ao criar lista de envio de mensagens"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.0.1"
    }
}

Exemplo de código Python#

import requests

url = "https://api.green-api.com/v1/broadcast"

payload = "{\r\n    \"name\": \"Broadcast from Green-API\",\r\n    \"to\": [\r\n        {\"wa_id\": \"5521985889090\"},\r\n        {\"wa_id\": \"5521985889991\"},\r\n        {\"wa_id\": \"5521985889098\"}\r\n    ],    \r\n    \"type\": \"text\",\r\n    \"text\": {\r\n        \"body\": \"I use Green-API to send this broadcast to you!\"\r\n    }\r\n}"
headers = {
  'Authorization': 'Bearer <your api token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))