/
API - Campanha - Importando múltiplos assinantes de uma campanha

API - Campanha - Importando múltiplos assinantes de uma campanha

Owned by Lucas Castro
Last updated: Apr 26, 2024 by Hamilton Reis (Unlicensed)
5 min read

O objetivo dessas APIs é de inserir assinantes, individualmente ou em lote, em uma campanha.

Para poder utilizar a API do Evolux Chat, é necessário primeiro Gerar um Token. Envie uma solicitação para o time de suporte que providenciaremos um Token para você.

Inserir assinantes via upload de um arquivo CSV

Enpoint

/api/v1/campaign/{{campaign_uuid}}/subscribers

Método

POST

  • UUID da Campanha
    Identificado universal da campanha, que pode ser coletado na URL de inserção dos assinantes da campanha, na interface do Evolux Chat (https://seudominio.evolux.cx/admin/campaigns)

  • Content-Type
    O Content-Type deve ser enviado através do cabeçalho da requisição (header) e indica o tipo do arquivo que está sendo importado. Nessa abordagem vamos realizar o envio de um arquivo, então o valor do campo deve ser text/csv

  • Autenticação
    A autenticação é feita inserindo um Cabeçalho "Authorization: Bearer <API-TOKEN>", onde <API-TOKEN> é a chave disponibilizada de maneira segura pelo Suporte Evolux.

  • Body
    O body da requisição é do tipo form-data, onde a chave é “file”, e o valor é o caminho do arquivo CSV.

tamanho máximo do arquivo é 50MB com um tempo limite de upload de 30 segundos. Caso seja necessário enviar uma quantidade maior de assinantes, a recomendação é dividir em várias requisições cada uma com no máximo 50MB.

 

A estrutura do arquivo CSV deve acompanhar aquilo que a campanha exige (veja mais em Campanhas - Evolux Chat ). Ou seja, a coluna name e phone são obrigatórias e, para cada parâmetro do template que a campanha usa, deve ser inserida na sequência uma coluna com o cabeçalho parameter, seguido do seu número (iniciado em 1). Por exemplo, uma campanha com três parâmetros precisará das colunas name, phone, parameter1, parameter2, parameter3. Qualquer coluna inserida após a sequência esperada será tratado como um dado customizado.
CUIDADO com a inserção de dados customizados, pois eles geram colunas PERMANENTES nos relatórios de Histórico de Atendimento e Histórico de Campanhas.

O padrão de número de telefone aceito deve sempre iniciar com o código do país (ex: 55) + código de área (no caso do BR, sem o zero à esquerda) + o número → 55XXPZZZZZZZZ

Ex: 5511981810101 ou 551154000019

Exemplos de Chamada (Python)

import requests url = "https://seudominio.evolux.cx/api/v1/campaign/713c38c6-d598-4963-9f82-c088a1e8986a/subscribers" payload = {} files=[ ('file',('subscriber_template.csv',open('~/Documents/subscriber_template.csv','rb'),'text/csv')) ] headers = { 'Authorization': 'Bearer <API-TOKEN>' } response = requests.request("POST", url, headers=headers, data=payload, files=files) print(response.text)

Exemplos de Chamada (cURL)

curl --location --globoff 'https://seudominio.evolux.cx/api/v1/campaign/713c38c6-d598-4963-9f82-c088a1e8986a/subscribers' \ --header 'Authorization: Bearer <API-TOKEN>' \ --form 'file=@"~/Documents/subscriber_template.csv"'

 

 

 

 

Inserir assinantes por um corpo em JSON

Enpoint

/api/v1/campaign/{{campaign_uuid}}/subscribers

Método

POST

  • UUID da Campanha
    Identificado universal da campanha, que pode ser coletado na URL de inserção dos assinantes da campanha, na interface do Evolux Chat (https://seudominio.evolux.cx/admin/campaigns)

  • Content-Type
    O Content-Type deve ser enviado através do cabeçalho da requisição (header) e indica o tipo do arquivo que está sendo importado. Nessa abordagem, vamos inserir os dados dos assinantes via texto em formato JSON, então o valor do campo deve ser application/json

  • Autenticação
    A autenticação é feita inserindo um Cabeçalho "Authorization: Bearer <API-TOKEN>", onde <API-TOKEN> é a chave disponibilizada de maneira segura pelo Suporte Evolux.

  • Body
    O corpo da requisição consiste em um arquivo de texto (RAW) com a sintaxe JSON.

 

A estrutura dos itens que compõe a lista de assinantes deve acompanhar aquilo que a campanha exige (veja mais em Campanhas - Evolux Chat ). Ou seja, as chaves name e phone são obrigatórias e, para cada parâmetro do template que a campanha usa, deve ser inserida uma chave parameter, seguida do seu número (iniciado em 1). Por exemplo, uma campanha com três parâmetros precisará das chaves name, phone, parameter1, parameter2, parameter3. Qualquer chave inserida após a sequência esperada será tratada como um dado customizado.
CUIDADO com a inserção de dados customizados, pois eles geram colunas PERMANENTES nos relatórios de Histórico de Atendimento e Histórico de Campanhas.

O padrão de número de telefone aceito deve sempre iniciar com o código do país (ex: 55) + código de área (no caso do BR, sem o zero à esquerda) + o número → 55XXPZZZZZZZZ

Ex: 5511981810101 ou 551154000019

Exemplos de Chamada (Python)

import requests import json url = "https://seudominio.evolux.cx/api/v1/campaign/713c38c6-d598-4963-9f82-c088a1e8986a/subscribers" payload = json.dumps([ { "phone": "55119XXXXXXXX", "name": "Fulano de Tal", "parameter1": "Fulano", "email": "fulanodetal@evolux.net.br", "cpf": "111.111.111-11", "tipo_sanguineo": "O+" }, { "phone": "55119XXXXXXXX", "name": "Ciclano de Tal", "parameter1": "Ciclano", "email": "ciclanodetal@evolux.net.br", "cpf": "111.111.111-00", "tipo_sanguineo": "A-" } ]) headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer <API-TOKEN>' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)

Exemplos de Chamada (cURL)

curl --location --globoff 'https://seudominio.evolux.cx/api/v1/campaign/713c38c6-d598-4963-9f82-c088a1e8986a/subscribers' \ --header 'Authorization: Bearer <API-TOKEN>' \ --form 'file=@"~/Documents/subscriber_template.csv"'

 

Retorno da chamada

Como essa API recebe a requisição e cadastra a tarefa para que ela seja executada pelo Evolux de maneira assíncrona, o retorno esperado diz respeito ao cadastramento dessa task, o resultado do processamento dos assinantes serão demonstrados mais abaixo.
Caso a requisição tenha sucesso, você receberá uma resposta com o código 202 - Accepted, e um dicionário JSON no corpo, indicando o sucesso e informando qual é o ID único dessa tarefa, dentro da chave data. Veja um exemplo abaixo:

{ "data": "5341e0ce-c346-4512-bcc4-6cc50a2a28ef", "message": "Accepted", "status": 202 }

 

 

Verificar o resultado do processamento dos assinantes

 

Essa API consultará a tarefa recebida pelo acionamento acima, e informará o status e o resultado da mesma, informando a quantidade de sucessos e fracassos na inserção de assinantes.

Enpoint

/api/v1/campaign/{{campaign_uuid}}/tasks/{{task_id.data}}

Método

GET

O UUID da campanha e o método de autenticação devem ser idênticos aos usados na chamada da API de inserção de assinantes.

 

Exemplos de Chamada (Python)

import requests url = "https://seudominio.evolux.cx/api/v1/campaign/78142880-9831-4c8a-bc39-1b26d5b9dc2c/tasks/5341e0ce-c346-4512-bcc4-6cc50a2a28ef" payload = {} headers = { 'Authorization': 'Bearer <API-TOKEN>' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text)

Exemplos de Chamada (cURL)

curl --location --globoff 'https://seudominio.evolux.cx/api/v1/campaign/78142880-9831-4c8a-bc39-1b26d5b9dc2c/tasks/5341e0ce-c346-4512-bcc4-6cc50a2a28ef' \ --header 'Authorization: Bearer <API-TOKEN>'

 

Retorno da chamada

Caso a requisição tenha sucesso, você receberá uma resposta com o código 200 - OK, e um dicionário JSON no corpo, indicando os dados da tarefa, como status, horários de criação e finalização, usuário responsável pelo cadastramento (dono do token) e o principal, que são os contadores da importação. Esse dado fica na chave counters e dá o quantitativo de assinantes ignorados, importados com sucesso, importados com algum erro, e o total de assinantes válidos. Veja um exemplo abaixo:

{ "campaign_uuid": "78142880-9831-4c8a-bc39-1b26d5b9dc2c", "counters": { "ignored": 0, "imported": 2, "imported_with_error": 0, "valid_subscriber_count": 2 }, "created_at": "Tue, 23 Apr 2024 16:23:28 GMT", "finished_at": "Tue, 23 Apr 2024 16:23:28 GMT", "status": "completed", "task_id": "5341e0ce-c346-4512-bcc4-6cc50a2a28ef", "task_uuid": "5341e0ce-c346-4512-bcc4-6cc50a2a28ef", "type": "subscriber_import", "user": { "email": "donodotoken@suaempresa.com.br", "name": "Pessoa dona do Token de Acesso" }, "when": "Tue, 23 Apr 2024 16:23:28 GMT" }

 

Related content