Ajuda

Você poderá criar campanhas de WhatsApp marketing de forma programática utilizando a nossa API de gestão de contatos e campanhas, utilize os métodos abaixo para começar a criar conteúdo em nossa plataforma de envio de WhatsApp marketing,

Para se integrar à API é necessário que você esteja autenticado e para isso é importante que você tenha acesso ao artigo "Como se integrar a API da MailerWeb?".

Passo 1 - Criando uma Campanha de Envio de WhatsApp Marketing

Com esse método você poderá programar sua campanha de WhatsApp marketing, mas antes você precisará criar o modelo de mensagem para envio. Informações poderão ser vistas em "Como criar um Modelo de Mensagem para envio de WhatsApp Marketing utilizando a API da MailerWeb".

Para interagir com as campanhas de WhatsApp Marketing, vamos criar o objeto com os seguintes parâmetros e com o seguinte endpoint:

• Campo "name" é utilizado apenas para identificar a nome da campanha, não será exibido ao destinatário
• Campo "whatsapp_template" é utilizado para designar qual o modelo de mensagem você deverá utilizar para enviar essa campanha.
• Campo "disable_click_track" é um campo do tipo booleando, onde você deve dizer se o sistema desativará o rastreamento de click, preservando as URLs e hiperlinks contidos na mensagem.
• Campo "lists" é utilizado para designar quais as listas que você utilizará para enviar as campanhas, será um campo do tipo lista, com vário itens, conforme formato abaixo:
  • /api/v1/contacts/static_list/id-da-lista-estatica/ se você desejar utilizar uma lista estática
  • /api/v1/contacts/dynamic_list/id-da-lista-dinamica/, se você desejar utilizar uma lista dinâmica. Campo "exclude_lists" é utilizado para designar quais listas cujo contatos também estejam no campo "lists", isso é feito para selecionar contatos que NAO devem receber a campanha, caso estejam designados no campos "lists"
• Campo "exclude_lists" é utilizado para designar que os contatos da campanha das listas selecionadas, estiverem na lista designada, não deverão receber a campanha, será um campo do tipo lista, com vário itens, conforme formato abaixo:
  • /api/v1/contacts/static_list/id-da-lista-estatica/ se você desejar utilizar uma lista estática
  • /api/v1/contacts/dynamic_list/id-da-lista-dinamica/, se você desejar utilizar uma lista dinâmica. Campo "exclude_lists" é utilizado para designar quais listas cujo contatos também estejam no campo "lists", isso é feito para selecionar contatos que NAO devem receber a campanha, caso estejam designados no campos "exclude_lists"
• Campo "click_lists" é utilizado para adicionar o contato a uma ou mais listas caso ele clique na campanha no link constante na mensagem da campanha

• Campo "use_my_number", é do tipo booleano. Você poderá definir se deseja utilizar seu próprio número para envio. Caso tenha optado por "true", será necessário autenticar seu telefone no painel de controle antes de prosseguir com a campanha, caso contrário a campanha será cancelada. Para autenticar o telefone você deverá seguir as instruções descritas na seção O meu número de WhatsApp sera utilizado para envio de mensagens?

• Campo "whatsapp_sender", se você optou por utiizar seu próprio número para envio, você deverá associar um registro de envio, ele será no formato abaixo:

  • /api/v1/campaigns/whatsapp_sender/id-do-numero-autorizado-para-envio - Caso você não informe esse registro, a campanha será cancelada.

• Campo "reply_mobile_number", é utilizado para as campanhas que utilizam o número da MailerWeb, você poderá definir um telefone para receber as respostas da sua campanha. Ele será colocado na mensagem no formato de um link para abertura do aplicativo do WhatsApp. Caso tenha marcada o opção use_my_number como verdadeiro, esse campo "reply_mobile_number" será ignorado.

• Campo "reply_call_to_action", é utilizado para as campanhas que utilizam o número da MailerWeb, você poderá definir um texto que combinado com o valor do "reply_mobile_number" criará um link com texto na mensagem, chamando o contato para clicar no número do WhatsApp. Caso tenha marcada o opção use_my_number como verdadeiro, esse campo "reply_call_to_action" será ignorado.

• Campo "reply_contact_text", é utilizado para as campanhas que utilizam o número da MailerWeb, você poderá definir um texto que será exibido dentro do aplicativo do WhatsApp Web do contato, para que o contato receptor não precise digitar nenhuma mensagem para você, bastando apenas de ter de enviar a mensagem. Caso tenha marcada o opção use_my_number como verdadeiro, esse campo "reply_contact_text" será ignorado.

• Campo "date_scheduled" é utilizado para definir a programação da campanha, deverá ser no formado YYYY-MM-DD HH:MM.

POST: /api/v1/campaigns/whatsapp_campaign/

{
    "name": "Teste",
    "whatsapp_template": "/api/v1/campaigns/whatsapp_template/id-do-whatsapp-template/",
    "disable_click_track": false,
    "lists": ["/api/v1/contacts/static_list/id-da-lista-estatica/",
              "/api/v1/contacts/dynamic_list/id-da-lista-dinamica/"],
    "exclude_lists": [],
    "open_lists": [],
    "click_lists": [],
    "reply_call_to_action": null,
    "reply_contact_text": "",
    "reply_mobile_number": null,
    "reply_to": null,
    "use_my_number": true,
    "whatsapp_sender": /api/v1/campaigns/whatsapp_sender/id-do-numero-autorizado-para-envio-pelo-whatsapp/,
    "date_scheduled": "2021-02-01 00:00"
}

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X POST --data data https://painel.mailerweb.com.br/api/v1/campaigns/whatsapp_campaign/ 

O resultado esperado será semelhante ao JSON abaixo:

{
    "click_lists": [],
    "clicked": 0,
    "current_item": null,
    "date_created": "2021-01-20T16:35:23",
    "date_finished": null,
    "date_scheduled": "2021-02-01T00:00:00",
    "date_started": null,
    "description": null,
    "disable_click_track": false,
    "error": 0,
    "exclude_lists": [],
    "id": id-campanha-whatsapp-marketing,
    "last_count": null,
    "limit_to": null,
    "lists": [
        {
            "contacts_hard_bounce": 0,
            "contacts_soft_bounce": 0,
            "contacts_valids": 1,
            "id": id-da-lista-estatica,
            "name": "teste 01",
            "total_contacts": 1
        }
    ],
    "media_file": "uploads/mailerweb/whatsapp-image-2018-03-11-at-203323.jpeg",
    "message": "Isso é um teste acesse www.mailerweb.com.br",
    "name": "Teste",
    "non_list_recipients": "",
    "open_lists": [],
    "opt_out": 0,
    "reply_call_to_action": null,
    "reply_contact_text": "",
    "reply_mobile_number": null,
    "reply_to": null,
    "resource_uri": "/api/v1/campaigns/whatsapp_campaign/id-da-campanha-whatsapp-marketing/",
    "status": "waiting",
    "success": 0,
    "total_answered": 0,
    "total_billed": 0,
    "total_scheduled": 0,
    "total_sent": 0,
    "use_my_number": true,
    "whatsapp_sender": /api/v1/campaigns/whatsapp_sender/id-do-numero-autorizado-para-envio-pelo-whatsapp/,
    "whatsapp_template": {
        "content": "Isso é um teste acesse www.mailerweb.com.br",
        "date_created": "2018-08-02",
        "id": id-do-whatsapp-template,
        "last_updated": "2018-08-26",
        "media_file": "uploads/mailerweb/whatsapp-image-2018-03-11-at-203323.jpeg",
        "name": "Teste",
        "resource_uri": "/api/v1/campaigns/whatsapp_template/id-do-whatsapp-template/"
    }
}

Repare que o ID da Campanha de Envio de WhatsApp Marketing está no atributo ID e no atributo resource_url, onde você poderá acessar os detalhes dessa campanha a partir do endpoint entregue por esse parâmetro. A partir de agora, grave esse ID, todos os detalhes de relatório e filtro de contatos você poderá fazer a partir desse ID.

Agora que você está de posse do ID da da Campanha de Envio de WhatsApp Marketing, vamos ao Passo 2:

Passo 2 - Listando as Campanhas de WhatsApp Marketing existentes

Para visualizar todas as campanhas de envio de WhatsApp marketing 

GET: /api/v1/campaigns/whatsapp_campaign/

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/campaigns/whatsapp_campaign/ 

O resultado será semelhante a esse

{
    "meta": {
        "limit": 50,
        "next": "/api/v1/campaigns/whatsapp_campaign/?limit=50&offset=50",
        "offset": 0,
        "previous": null,
        "total_count": 70
    },
    "objects": [
        {
            "click_lists": [],
            "clicked": 0,
            "current_item": null,
            "date_created": "2018-08-02T14:34:06",
            "date_finished": "2018-08-02T14:34:17",
            "date_scheduled": "2018-08-02T14:34:06",
            "date_started": "2018-08-02T14:34:11",
            "description": null,
            "disable_click_track": false,
            "error": 0,
            "exclude_lists": [],
            "id": id-da-campanha,
            "last_count": null,
            "limit_to": null,
            "lists": [
                {
                    "contacts_hard_bounce": 0,
                    "contacts_soft_bounce": 4,
                    "contacts_valids": 16,
                    "id": id-da-lista,
                    "name": "Teste Envio",
                    "resource_uri": "",
                    "total_contacts": 20
                }
            ],
            "media_file": "uploads/mailerweb/whatsapp-image-2018-03-11-at-203323.jpeg",
            "message": "Isso é um teste",
            "name": "Teste",
            "non_list_recipients": "",
            "opt_out": 0,
            "reply_call_to_action": null,
            "reply_contact_text": "",
            "reply_mobile_number": null,
            "reply_to": null,
            "resource_uri": "/api/v1/campaigns/whatsapp_campaign/id-da-campanha/",
            "status": "finished",
            "success": 5,
            "total_answered": 0,
            "total_billed": 5,
            "total_scheduled": 5,
            "total_sent": 5,
            "use_my_number": false,
            "whatsapp_template": {
                "content": "Isso é um teste acesse www.mailerweb.com.br",
                "date_created": "2018-08-02",
                "id": 38263,
                "last_updated": "2018-08-26",
                "media_file": "uploads/mailerweb/whatsapp-image-2018-03-11-at-203323.jpeg",
                "name": "Teste",
                "resource_uri": "/api/v1/campaigns/whatsapp_template/id-do-template/"
            }
        }....
    ]
}

Importante notar que será exibido um objeto no formato JSON, onde virão 2 dicionários: meta e objects, a saber:

• Em "meta" você terá uma visão geral de quantos objetos você possui e ainda o link da próxima página do objeto, isso estará no atributo "next" do dicionário;
• Em objects, você terá um detalhe completo do objeto carregado no campo resource_uri, terá o link para chamar para a atualização desse objeto.

Você também poderá consultar objetos de acordo com os atributos existentes nesse formulário, por exemplo:

Listando os modelos por ID da Campanha:

GET: /api/v1/campaigns/whatsapp_campaign/?id=xxx

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/campaigns/whatsapp_campaign/?id=xxxx 

Listando os modelos por nome:

GET: /api/v1/campaigns/whatsapp_campaign/?name=teste

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/campaigns/whatsapp_campaign/?name=teste 

Listando os modelos por status da campanha:

GET: /api/v1/campaigns/whatsapp_campaign/?status=progress

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/campaigns/whatsapp_campaign/?subject=progress

Os status disponíveis para consulta são:

STATUS_CHOICES = (
        ('counting', _('Contando os Contatos')),
        ('processing', _('Processando Contatos')),
        ('moderating', _('Em Moderação')),
        ('waiting', _('Programada')),
        ('progress', _('Enviando')),
        ('finished', _('Finalizada')),
        ('paused', _('Pausada')),
        ('suspended', _('Interrompida')),
        ('canceled', _('Cancelada')),
)

Passo 3 - Atualizando uma Campanha de Envio de WhatsApp Marketing

Você pode necessitar alterar um item da campanha de envio de whatsapp marketing como por exemplo a data de envio, nesse caso você utilizar o método PATCH com os parâmetros abaixo:

PATCH: /api/v1/campaigns/whatsapp_campaign/XXX58/

data = {
   'date_scheduled': '2021-03-15 00:40'
}

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X PATCH --data data https://painel.mailerweb.com.br/api/v1/campaigns/whatsapp_campaign/XXX58/ 

IMPORTANTE: Somente campanhas que estiverem programadas ou em andamento poderão ser atualizados, os demais estados não permite a atualização da campanha. Você poderá alterar o status da campanha, desde que ela não tenha sido finalizada, suspensa ou cancelada.

Agora você poderá criar campanhas, obter relatórios de dados em tempo real em sua aplicação.