Como criar uma campanha de SMS Marketing utilizando a API da MailerWeb
Você poderá criar campanhas de SMS 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 SMS 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 SMS Marketing
Com esse método você poderá programar sua campanha de SMS 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 SMS Marketing utilizando a API da MailerWeb".
Para interagir com as campanhas de SMS 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 "sms_template" é utilizado para designar qual o modelo de mensagem você deverá utilizar para enviar essa campanha.
- 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 "date_scheduled" é utilizado para definir a programação da campanha, deverá ser no formado YYYY-MM-DD HH:MM.
POST: /api/v1/campaigns/sms_campaign/
data = {
"name": "Teste",
"sms_template": "/api/v1/campaigns/sms_template/id-do-sms-template/",
"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": [],
"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/sms_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,
"error": 0,
"exclude_lists": [],
"id": id-campanha-sms-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
}
],
"message": "Isso é um teste acesse www.mailerweb.com.br",
"name": "Teste",
"non_list_recipients": "",
"opt_out": 0,
"resource_uri": "/api/v1/campaigns/sms_campaign/id-da-campanha-sms-marketing/",
"status": "waiting",
"success": 0,
"total_answered": 0,
"total_billed": 0,
"total_scheduled": 0,
"total_sent": 0,
"use_my_number": false,
"sms_template": {
"content": "Isso é um teste acesse www.mailerweb.com.br",
"date_created": "2018-08-02",
"id": id-do-sms-template,
"last_updated": "2018-08-26",
"name": "Teste",
"resource_uri": "/api/v1/campaigns/sms_template/id-do-sms-template/"
}
}
Repare que o ID da Campanha de Envio de SMS 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 SMS Marketing, vamos ao Passo 2:
Passo 2 - Listando as Campanhas de SMS Marketing existentes
Para visualizar todas as campanhas de envio de SMS marketing
GET: /api/v1/campaigns/SMS_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/sms_campaign/
O resultado será semelhante a esse
{
"meta": {
"limit": 50,
"next": "/api/v1/campaigns/sms_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,
"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
}
],
"message": "Isso é um teste",
"name": "Teste",
"non_list_recipients": "",
"opt_out": 0,
"resource_uri": "/api/v1/campaigns/sms_campaign/id-da-campanha/",
"status": "finished",
"success": 5,
"total_answered": 0,
"total_billed": 5,
"total_scheduled": 5,
"total_sent": 5,
"sms_template": {
"content": "Isso é um teste acesse www.mailerweb.com.br",
"date_created": "2018-08-02",
"id": id-do-template,
"last_updated": "2018-08-26",
"name": "Teste",
"resource_uri": "/api/v1/campaigns/sms_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/sms_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/sms_campaign/?id=xxxx
Listando os modelos por nome:
GET: /api/v1/campaigns/sms_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/sms_campaign/?name=teste
Listando os modelos por status da campanha:
GET: /api/v1/campaigns/sms_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/sms_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 SMS Marketing
Você pode necessitar alterar um item da campanha de envio de SMS 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/sms_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/sms_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.