API - Relatório - Histórico das Campanhas

O que essa API faz?

Ela retorna, de maneira estruturada, todos os registros gerados no Evolux Chat, que correspondem à assinantes (contatos) inseridos dentro de uma campanha para disparo automático via Whatsapp.

A quem pode interessar essa API?

Essa API pretende ajudar desenvolvedores, analistas de BI ou qualquer pessoa que precise trabalhar com os dados do Relatório de Campanhas do Evolux Chat para realizar consultas automatizadas, geração de insights, análise visual de dados, entre outras finalidades.

É simples utilizar?

Basicamente você fará uma requisição web, utilizando o método GET, para o endereço https://seuservidor.evolux.cx/api/v1/reports/campaign/subscribers. Para se autenticar, basta passar um Bearer Token no cabeçalho, com a chave de acesso que foi disponibilizada pelo nosso Suporte

Passo a passo:

URL	https://SEUSERVIDOR.evolux.cx
Endpoint	/api/v1/reports/campaign/subscribers
Método	GET
Autenticação	Bearer Token

Parâmetros

chave	Tipo aceito no valor	Descrição
phone_number	string	Número de telefone do assinante (ex: 1199881122)
name	string	Nome do assinante (ex: Maria do Carmo)
state	string	Status daquele disparo. As opções válidas são: pending : Mensagem não foi disparada, está pendente; scheduled : Mensagem está agendada; sent : Mensagem foi enviada, porém ainda não houve interação do cliente; dnd : Assinante foi inserido em uma lista de Não Perturbe; completed : Mensagem foi disparada e o cliente interagiu com ela; error : Erro no disparo, pode ser template da Meta com restrição, pode ser que o contato já tenha uma conversa ativa na plataforma, entre outros.
template_uuid	UUID	UUID do template (solicitar ao Suporte Evolux) Ex: 70f4ddb6-ece1-4e13-ab90-3698d9d72bf0
campaigns[]	UUID	UUID que fica exposto na url da gestão de uma determinada campanha; (Aceita repetição dessa mesma chave, com o UUID de outras campanhas) Ex: f45d98dc-ac5e-48f2-9c01-ebe18f86d28b
start	ISO Date	Data de corte inicial para o momento da inserção do assinante na campanha Ex: 2024-08-03T03%3A00%3A00.000Z
end	ISO Date	Data de corte final para o momento da inserção do assinante na campanha Ex: 2024-08-04T02%3A59%3A59.999Z
timezone	string	Fuso Horário (Ex: America/Sao_Paulo)
conversation_field_key	string	Nome de algum campo customizado (precisa do valor) Ex: CPF
conversation_field_value	string	Valor de algum campo customizado (precisa do campo) Ex: 111.111.111-11

Exemplos de uso:

Caso 1 : Quero ver todos os assinantes que foram inseridos entre o dia 05 e 06 de setembro de 2024, cujo perfil (inserido em um campo customizado da campanha) seja “Pessoa Jurídica”, independente de qual campanha estão participando.

Requisição em cURL:

curl --location 'https://accenture.evolux.cx/api/v1/reports/campaign/subscribers?timezone=America%2FSao_Paulo&start=2024-09-05T00%3A00%3A00.000Z&end=2024-09-06T02%3A59%3A59.999Z&conversation_field_key=perfil&conversation_field_value=Pessoa%20Jur%C3%ADdica' \
--header 'Authorization: Bearer ********-****-****-****-************'

Requisição em Python:

import requests

# URL base
url = "https://seuservidor.evolux.cx/api/v1/reports/campaign/subscribers"

# Parâmetros da requisição
params = {
    'start': '2024-09-05T00:00:00.000Z',
    'end': '2024-09-06T23:59:59.999Z',
    'conversation_field_key': 'perfil',
    'conversation_field_value': 'Pessoa Jurídica'
}

# Cabeçalhos da requisição
headers = {
    'Authorization': 'Bearer ********-****-****-****-************'
}

# Realizando a requisição GET com os parâmetros e cabeçalhos
response = requests.get(url, headers=headers, params=params)

# Imprimindo a resposta
print(response.text)

Retorno esperado:

{
    "data": [
        {
            "campaign_name": "Campanha - Teste",
            "conversation_field_values": {
                "cpf": "111.111.111-11",
                "id_cliente": "13",
                "id_proposta": "133",
                "perfil": "Pessoa Jurídica",
                "modelo": "Modelo Teste",
                "produto": "Produto Teste"
            },
            "conversation_uuid": "1a42d273-97f0-4d36-bd78-446c991030fa",
            "error_message": null,
            "name": "Fulano de Tal",
            "phone_number": "+5531997665448",
            "replied_at": null,
            "reply_action": null,
            "reply_text": null,
            "sent_at": "2024-09-05T14:01:50+00:00",
            "state": "sent",
            "template": "template_de_teste"
        },
        {
            "campaign_name": "Campanha - Teste",
            "conversation_field_values": {
                "cpf": "222.222.222-22",
                "id_cliente": "14",
                "id_proposta": "144",
                "perfil": "Pessoa Jurídica",
                "modelo": "Modelo Teste 2",
                "produto": "Produto Teste 2"
            },
            "conversation_uuid": "2b53e384-97f0-4d36-bd78-446c991030bb",
            "error_message": null,
            "name": "Beltrano da Silva",
            "phone_number": "+5511971665489",
            "replied_at": null,
            "reply_action": null,
            "reply_text": null,
            "sent_at": "2024-09-05T13:09:10+00:00",
            "state": "sent",
            "template": "template_de_teste"
        },
        {
            "campaign_name": "Campanha - Teste",
            "conversation_field_values": {
                "cpf": "333.333.333-33",
                "id_cliente": "12",
                "id_proposta": "122",
                "perfil": "Pessoa Jurídica",
                "modelo": "Modelo Teste",
                "produto": "Produto Teste"
            },
            "conversation_uuid": "4x55r431-97f0-4d36-bd78-446c99454e4r",
            "error_message": null,
            "name": "Cristiano do Carmo",
            "phone_number": "+5516987765000",
            "replied_at": null,
            "reply_action": null,
            "reply_text": null,
            "sent_at": "2024-09-05T09:02:30+00:00",
            "state": "sent",
            "template": "template_de_teste"
        }
    ],
    "message": "OK",
    "pagination": {
        "total": 3
    },
    "status": 200
}

Para especificar uma data, orientamos utilizar a chave “timezone” da sua região (ex: America/Sao_Paulo) e também inserir o horário de início e término de acordo com o seu fuso (ex: em São Paulo, inserir 3 horas para frente)

Caso sejam obtidos mais retornos do que o especificado no parâmetro “limit” (padrão são 50), a chave “pagination” entrega um valor dentro de “next” que pode ser utilizado como endpoint para a próxima requisição, a fim de obter os resultados da página seguinte.

], "message": "OK", "pagination": { "next": "/api/v1/reports/campaign/subscribers?_limit=50&_offset=50", "total": 6100 }, "status": 200

}

Caso 2 : Quero obter o resultado de hoje, até o momento, das campanhas “Teste - 1" e “Teste - 2”, cujos uuids são respectivamente, f45d98dc-ac5e-48f2-9c01-ebe18f86d28b e e629ed93-0ab7-4319-accb-813330938f84

Requisição em cURL:

curl --location --globoff 'https://seuservidor.evolux.cx/api/v1/reports/campaign/subscribers?campaigns[]=f45d98dc-ac5e-48f2-9c01-ebe18f86d28b&timezone=America%2FSao_Paulo&campaigns[]=e629ed93-0ab7-4319-accb-813330938f84&state=error' \
--header 'Authorization: Bearer ********-****-****-****-************'

Requisição em Python:

import requests

url = "https://seuservidor.evolux.cx/api/v1/reports/campaign/subscribers"

params = {
    "campaigns[]": [
        "f45d98dc-ac5e-48f2-9c01-ebe18f86d28b",
        "e629ed93-0ab7-4319-accb-813330938f84"
    ],
    "state": "error"
}

headers = {
    'Authorization': 'Bearer ********-****-****-****-************'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Alguns outros possíveis retornos:

401 - Seu método de autenticação falhou

{
    "message": "Unauthorized",
    "status": 401
}

429 - Você está fazendo requisições mais rapidamente do que o servidor pode suportar

{
    "message": "Too Many Requests",
    "status": 429
}

404 - O endpoint que você está tentando acessar não existe, confira se ele foi escrito corretamente

{
    "error_message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
    "message": "Not Found",
    "status": 404
}

404 - A data de início precisa existir e ser menor do que a de fim

{
    "error_message": "Start date should not be greater than end date.",
    "key": "start",
    "message": "Not Found",
    "status": 404
}

404 - A data de fim não pode ser maior do que a atual (de acordo com o fuso informado)

{
    "error_message": "End date in future.",
    "key": "end",
    "message": "Not Found",
    "status": 404
}

500 - Alguns motivos não mapeados podem levar a um erro 500. Confira se algum parâmetro declarado está com valor de tipo diferente do esperado (ex: indicar um UUID de campanha como um numero inteiro), ou se a URL está escrita corretamente.