04. API de Dados Zenvia Chat

Esta API possibilita a consulta de dados das interações realizadas via Zenvia Chat, conforme relatórios já extraídos atualmente, a partir da interface de Administração.

TOKEN

O token de acesso à API pode ser gerado na interface de Administração, a partir do menu:

Configurações
Integrações
API

Link: https://zchat-admin.zenvia.com/integrations

CANAIS DIGITAIS

Equivalente ao relatório Canais Digitais, possibilita a consulta de dados consolidados, referentes aos atendimentos realizados.

Get interactions report:

GET: https://zchat.zenvia.io/api/ms/external/reports?token=yourApiToken

Parâmetros

data_type: dado pelo qual o agrupamento dos dados será realizado.
- period
- tag
- department
- channel
- agent

Obs: Caso não informado, o agrupamento padrão será o período.

from: Data de início do período, no padrão AAAA-MM-DD HH:MM:SS
- Ex: 2021-04-01T06:00:00
- Caso não informado, será feita a busca dos últimos 30 dias
to: Data final do período, no padrão AAAA-MM-DD HH:MM:SS
- Ex: 2021-04-30T18:00:00
- Caso não informado, será feita a busca até a data atual.
timezone: Timezone desejado, no padrão de 5 dígitos.
- Ex: -0300
- Caso não informado será utilizado o padrão UTC
agents: ID dos agentes, separados por vírgula, para consultas por agentes específicos.
- Caso não informado, será feita a busca por todos os agentes.
departments: Id dos departamentos, separados por vírgula, para consultas por departamentos específicos.
- Caso não informado, será feita a busca por todos os departamentos.
states: Consulta por interações com status específicos.
- Ex: 'ENDED', 'UNAVAILABLE', 'CANCELED' ou 'DISCARDED'
- Caso não informado, será feita a busca por todos os status.
types: Canal pelo qual a interação foi realizada.
- PHONE - Interações por chamadas de voz
- PHONE_CONF - Conferências por chamadas de voz
- WHATSAPP - Interações por WhatsApp
- FACEBOOK - Interações por Facebook
- EMAIL - Interações por e-mail
- SMS - Interações por SMS
- TELEGRAM - Interações por Telegram
- TEXT - Interações por Web Chat
- MELI_QST - Interações por perguntas no Mercado Livre
- MELI_MSG - Interações por pós-venda do Mercado Livre

Obs: Caso não informado, será feita a busca por todos os canais.

agents: ID das tags, separadas por vírgula, para consultas por interações com tags específicas.

Obs: Caso não informado, será feita a busca por todas as tags.

Para saber como interpretar os dados de retorno de sucesso da tabela abaixo, confira nossos exemplos:

String: Usado para textos e identificadores alfanuméricos. Exemplo: "messageId": "abc123"
Numeric: Representa números inteiros ou decimais. Exemplo: "price": 0.05
Boolean: Para valores verdadeiros ou falsos. Exemplo: "success": true
Date/Time: Para representar datas e horários. Exemplo: "timestamp": "2024-12-04T12:00:00Z"
Array: Listas de itens. Exemplo: "recipients": ["123456789", "987654321"]
Object: Estruturas aninhadas contendo múltiplos atributos. Exemplo: "metadata": {"key": "value"}

Retorno de Sucesso:

 "data": [
        {
          "answered": 3,
          "backlog": 14,
          "discarded": 2,
          "ended": 3,
          "expired": 0,
          "made": 0,
          "missed": 0,
          "not_answered": 0,
          "pending": 0,
          "postponed": 0,
          "received": 3,
          "remainder": 12,
          "sla": 17,
          "slapr": 0
          "title": "2020-02-02",
          "tma": 13,
          "tmaxe": 13,
          "tme": 4,
          "tmp": 0,
          "tmpa": 0,
          "tmpr": 11,
          "tmr": 2
        },
        {
          "answered": 3,
          "backlog": 14,
          "discarded": 2,
          "ended": 3,
          "expired": 0,
          "made": 0,
          "missed": 0,
          "not_answered": 0,
          "pending": 0,
          "postponed": 0,
          "received": 3,
          "remainder": 12,
          "sla": 17,
          "slapr": 0
          "title": "Total",
          "tma": 13,
          "tmaxe": 13,
          "tme": 4,
          "tmp": 0,
          "tmpa": 0,
          "tmpr": 11,
          "tmr": 2
        }
    	],
    "status": 200,
    "success": true
  }

Retorno de Erro:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

Significado das Variáveis:

title = Título
backlog = Sobra Anterior (Atendimentos que não foram finalizados no dia anterior)
received = Recebidos (Total de atendimentos novos recebidos no período)
made = Efetuados (Total de atendimentos iniciados pelo agente)
rang = Distribuídos (Atendimentos distribuídos automaticamente para o agente)
answered = Realizados (Atendimentos recebidos por um agente e realizados com troca de mensagem)
ended = Finalizados (Atendimentos realizados com troca de mensagem e marcados como finalizados pelo agente)
not_answered = Em fila (Atendimentos não realizados e que ficaram em fila para atendimento)
pending = Pendentes (agente) (Atendimentos iniciados e colocados na lista de pendentes (última interação do cliente))
postponed = Pendentes (cliente) (Atendimentos iniciados e colocados na lista de pendentes (última interação do agente))
discarded = Descartadas (Atendimentos recebidos por um agente, mas interrompidos sem troca de mensagem)
missed = Perdidos (Atendimentos inativos que foram encerrados pelo agente)
expired = Inativos (Atendimentos que expiraram e não podem mais ser respondidos)
remainder = Sobra do dia (Atendimentos não finalizados no dia mas que ainda poderão ser realizados)
tma = Tma (Tempo médio de atendimento em andamento (segundos))
tme = Tme (Tempo médio de espera do cliente em fila (segundos))
tmaxe = TmaxE (Tempo máximo de espera do cliente em fila (segundos))
tmpr = Tmpr (Tempo médio de primeira resposta do agente (segundos))
tmr = Tmr (Tempo médio de resposta do agente em atendimento (segundos))
tmpa = Tmpa (Tempo médio para o agente retomar um atendimento pendente (segundos))
tmp = Tmp (Tempo médio para o cliente retomar um atendimento pendente (segundos))
sla = Ttm (Tempo total médio de atendimento do contato do cliente à finalização do agente (TMA + TME + TMPA) (segundos))
slapr = SLA de primeira resposta

HISTÓRICO DE ATENDIMENTOS

Equivalente ao relatório “Histórico de Atendimentos”, possibilita a consulta de todos os dados referentes aos atendimentos realizados, tanto no formato padrão quanto no expandido.

Get History:

GET: https://zchat.zenvia.io/api/ms/external/history?token=yourApiToken

Get Expanded History

GET: https://zchat.zenvia.io/api/ms/external/history/expanded?token=yourApiToken

Parâmetros:

from: Data de início do período, no padrão AAAA-MM-DD HH:MM:SS
- Ex: 2021-04-01T06:00:00
- Caso não informado, será feita a busca dos últimos 30 dias
to: Data final do período, no padrão AAAA-MM-DD HH:MM:SS
- Ex: 2021-04-30T18:00:00
- Caso não informado, será feita a busca até a data atual.
timezone: Timezone desejado, no padrão de 5 dígitos
- Ex: -0300
- Caso não informado será utilizado o padrão UTC
active: Define se busca será feita por interações efetuadas ou recebidas
- “true” = Efetuadas (interações iniciadas pelos agentes)
- “false” = Recebidas (interações iniciadas pelos usuários)
- Caso não informado, será feita a busca por todas as interações
agents: ID dos agentes, separados por vírgula, para consultas por agentes específicos
- Caso não informado, será feita a busca por todos os agentes
departments: Id dos departamentos, separados por vírgula, para consultas por departamentos específicos
- Caso não informado, será feita a busca por todos os departamentos
states: Consulta por interações com status específicos
- Ex: 'ENDED', 'UNAVAILABLE', 'CANCELED' ou 'DISCARDED'
- Caso não informado, será feita a busca por todos os status
types: Canal pelo qual a interação foi realizada
- PHONE - Interações por chamadas de voz
- PHONE_CONF - Conferências por chamadas de voz
- WHATSAPP - Interações por WhatsApp
- FACEBOOK - Interações por Facebook
- EMAIL - Interações por e-mail
- SMS - Interações por SMS
- TELEGRAM - Interações por Telegram
- TEXT - Interações por Web Chat
- MELI_QST - Interações por perguntas no Mercado Livre
- MELI_MSG - Interações por pós-venda do Mercado Livre

Obs: Caso não informado, será feita a busca por todos os canais

search: Consulta por nome de cliente, e-mail de agente ou Id de interação específicos
- Ex:
  - search=maria -> fará uma busca por usuários ou email de agentes com o campo ILIKE '%maria%'
  - search=999 -> fará uma busca por usuários ou e-mail de agentes com o campo ILIKE '%999%' ou interaction_id=999
limit: número máximo de interações por requisição, com limite de 10.000 registros
- Caso não informado, serão apresentados 100 registros por requisição
page: Paginação para número de registros acima do limite por requisição (>=1)
- Caso não informado, serão apresentados apenas os registros dentro do limite da página 1

Obs: Deve ser aplicado um tratamento na resposta da requisição, para validar se o número de registros atinge o limite da página. Neste caso, uma nova requisição deve ser realizada, solicitando os registros da página seguinte.

Retorno de Sucesso:

{
  "status": 200,
  "success": true,
  "data": [{
  "active": "true/false" (who initiated the contact (sent/received)),
  "agent": {
    "id": "id" (agent_id),
    "name": "name" (agent_name),
    "phone_extension": "phone_extension" (agent_phone_extension)
  },
  "created_at": "created_at_iso" (interaction created_at),
  "current_state": "status" (interaction last status),
  "current_state_time": "current_state_time_iso" (interaction last status time),
  "customer": {
    "id"': "id" (customer id),
    "fields": { (each field can be an string or array (single/multiple fields))
    "channel_email": ["phone_1", "phone2"],
    "channel_external": "",
    "channel_facebook": "",
    "channel_mercado_livre": "",
    "channel_phone": "",
    "channel_telegram": "",
    "document": "",
    "main_identifier": "Example",
    "main_photo": ""
  }
  },
  "department": {
    "id": "department_id",
    "name": "department_name"
  },
  "first_answer_time": "first_answer_time_iso",
  "id": "protocol",
  "media": "service channel",
  "mood": "rating" (satisfaction survey),
  "Caso não tenha nenhum SLA pra interação, vai retornar "slas": []
Caso haja, vai retornar uma lista tipo essa:
"slas": [
{
"id": 888,
"sla_ended_at": "2023-10-03T13:00:00"
"sla_expired": true,
"sla_name": "sla_queued_time", 
"sla_started_at": "2023-10-03T12:59:30",
"sla_time": 20
},
{

"id": 887,
"sla_ended_at": "2023-10-03T13:00:02",
"sla_expired": true,
"sla_name": "sla_first_reply_time",
"sla_started_at": "2023-10-03T12:59:30",
"sla_time": 30
},
{
"id": 889,
"sla_ended_at": "2023-10-03T13:00:13",
"sla_expired": false,
"sla_name": "sla_message_time",
"sla_started_at": "2023-10-03T13:00:10",
"sla_time": 10
}
]
  }]
}

Retorno de Erro:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

Significado das Variáveis:

expired = Inativo (Atendimento que expirou e não pode mais ser respondido)
expired_time = Tempo Inativo (Tempo que o atendimento inativo levou para ser encerrado pelo agente) (em segundos)
missed = Perdido (Atendimento inativo que foi encerrado pelo agente)
canceled = Abandonado pelo cliente (Atendimento interrompido pelo cliente antes de ser iniciado)
answered = Realizado (Por quantos agentes o atendimento foi realizado)
queued = Em Fila (Quantas vezes o atendimento foi para fila)
ended = Finalizado (Atendimento com troca de mensagem finalizado pelo agente)
discarded = Descartado pelo agente (Atendimento recebido mas interrompido pelo agente)
ringing = Distribuição (Quantas vezes o atendimento foi distribuído entre agentes)
postponed = Pendente (aguardando cliente) (Quantas vezes o atendimento foi colocado na lista de pendentes (última interação do agente) após iniciado)
pending = Pendente (aguardando agente) (Quantas vezes o atendimento foi colocado na lista de pendentes (última interação do cliente) após iniciado)
transferring = Transferido (Quantas vezes o atendimento foi transferido)
messages = Total de mensagens (Número de mensagens trocadas entre agente e cliente)
queued_time = Tempo em Fila (Tempo que o atendimento ficou em fila ou não atendida) (em segundos)
ringing_time = Tempo em distribuição (Tempo que o atendimento ficou tocando para os agentes) (em segundos)
missed_time = Tempo Perdido (Tempo para o atendimento inativo ser encerrado) (em segundos)
canceled_time = Tempo para abandono (Tempo até o abandono do cliente) (em segundos)
talking_time = Tempo em atendimento (Tempo que o atendimento ficou em andamento) (em segundos)
postponed_time = Tempo aguardando cliente (Tempo que o atendimento ficou aguardando mensagem do cliente) (em segundos)
pending_time = Tempo aguardando agente (Tempo que o atendimento ficou aguardando mensagem do agente) (em segundos)
first_contact_time = Tempo para primeira resposta (Tempo que o agente levou para responder a primeira mensagem do cliente) (em segundos)
response_count = Quantidade de respostas (Quantidade de trocas de cliente para agente)
response_time = Tempo médio de resposta (Tempo médio de resposta do agente no atendimento) (em segundos)
sla_time = Tempo total do atendimento (Tempo entre a primeira mensagem do cliente e a finalização do atendimento) (em segundos)
discarded_time = Tempo para descarte (Tempo até o descarte do agente) (em segundos)
browser = Navegador (Navegador do cliente que entrou em contato)
ip = Endereço IP (IP do cliente que entrou em contato)
os = Sistema operacional (SO do cliente que entrou em contato)
source = URL de origem (Url de onde o cliente foi redirecionado para o site do atendimento)
channel_external = Id Externo
group_name = Nome do Grupo
channel_email = Email (E-mail do cliente que entrou em contato)
channel_phone = Telefone (Telefone do cliente que entrou em contato)
channel_mercado_livre = Id Mercado Livre
channel_facebook = Id Facebook
channel_telegram = Id Telegram
document = CPF (CPF do cliente que entrou em contato)
main_identifier = Nome (Nome do cliente que entrou em contato)
agent = Agente (Agente que finalizou o atendimento)
phone_extension = Ramal (Ramal do agente que finalizou o atendimento)
department = Departamento (Departamento responsável pelo atendimento)
endTime = Última atualização (Data e hora da última atualização de status do atendimento)
id = Protocolo (Número de protocolo do atendimento)
origin = Origem (Quem iniciou o contato)
startTime = Primeira mensagem (Data e hora da primeira mensagem recebida pelo agente no atendimento)
state = Status (Atendimento perdido ou finalizado)
type = Canal (Canal do atendimento)
tagCount = Tags (Número de tags usadas no atendimento)
tags = Tags (Tags usadas no atendimento)
mood = Avaliação (Avaliação do cliente na pesquisa de satisfação do atendimento)
notes = Anotações
slas = SLAs (Service Level Agreement) registrados para o atendimento. Lista de objetos com os SLAs aplicados, contendo as seguintes informações:
- id = ID (Identificador do SLA)
- sla_name = Tipo de SLA, podendo ser:
  - sla_service_time – SLA de atendimento (Tempo decorrido entre a atribuição da interação a um agente e o encerramento da interação);
  - sla_queued_time – SLA de espera (Tempo decorrido entre a criação da interação e a atribuição a um agente);
  - sla_first_reply_time – SLA de primeira resposta (Tempo decorrido entre a criação da interação e a primeira mensagem enviada pelo agente);
  - sla_message_time – SLA de mensagem (Tempo decorrido entre uma mensagem enviada pelo cliente e a resposta do agente).
- sla_time = Tempo (Tempo configurado do SLA, em segundos)
- sla_started_at = Início (Data e hora em que o SLA começou a ser contado
- sla_ended_at = Fim (Data e hora em que o SLA foi encerrado)
- sla_expired = Expirado (Indica se o SLA foi expirado – true ou false)

HISTÓRICO DE CONVERSA

Para consulta do histórico de mensagens de uma uma conversa específica, pode ser utilizado o comando abaixo:

Get Protocol Messages:

GET: https://zchat.zenvia.io/api/ms/external/history/{id}/messages?token=yourApiToken

Parâmetro:

id: este parâmetro deve ser substituído pelo número do protocolo que se deseja consultar.

Retorno de Sucesso: :

{
  "data": [
    {
      "origin": "AGENT",
      "payload": "Your position in queue is 1",
      "timestamp": "2021-02-12T19:37:50",
      "type": "text",
      "url": null
    },
    {
      "origin": "CLIENT",
      "payload": "Something",
      "timestamp": "2021-02-12T19:28:36",
      "type": "image",
      "url": "https://omz-files-socialmedias.s3.amazonaws.com/test"
    }
  ],
  "status": 200,
  "success": true
}

Retorno de Erro:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

ATENDIMENTOS EM ANDAMENTO

Possibilita a consulta de dados dos atendimentos em andamento. Equivalente aos relatórios “Monitoramento”, “Fila de Espera”, “Pendentes” e “Inativos”.

Get ongoing interactions:

GET: https://zchat.zenvia.io/api/ms/external/ongoing?token=yourApiToken

Parâmetros:

agents: ID dos agentes, separados por vírgula, para consultas por agentes específicos.

Caso não informado, será feita a busca por todos os agentes.

departments: Id dos departamentos, separados por vírgula, para consultas por departamentos específicos.

Caso não informado, será feita a busca por todos os departamentos

states: Consulta por interações com status específicos. Ex: ‘NOT_ANSWER’, 'QUEUED', 'TALKING', 'RINGING', 'MISSED', 'PENDING', 'POSTPONED'

Caso não informado, será feita a busca por todos os status.

types:Canal pelo qual a interação foi realizada:
- PHONE - Interações por chamadas de voz
- PHONE_CONF - Conferências por chamadas de voz
- WHATSAPP - Interações por WhatsApp
- FACEBOOK - Interações por Facebook
- EMAIL - Interações por e-mail
- SMS - Interações por SMS
- TELEGRAM - Interações por Telegram
- TEXT - Interações por Web Chat
- MELI_QST - Interações por perguntas no Mercado Livre
- MELI_MSG - Interações por pós-venda do Mercado Livre

Obs: Caso não informado, será feita a busca por todos os canais.

limit: número máximo de interações por requisição, com limite de 10.000 registros.

Caso não informado, serão apresentados 100 registros por requisição.

page: Paginação para número de registros acima do limite por requisição (>=1).

Caso não informado, serão apresentados apenas os registros dentro do limite da página 1.

Retorno de Sucesso:

{
  "status": 200,
  "success": true,
  "data": [{
  "active": "true/false" (who initiated the contact (sent/received)),
  "agent": {
    "id": "id" (agent_id),
    "name": "name" (agent_name),
    "phone_extension": "phone_extension" (agent_phone_extension)
    "status": "ONLINE/OFFLINE"
  },
  "created_at": "created_at_iso" (interaction created_at),
  "current_state": "status" (interaction last status),
  "current_state_time": "current_state_time_iso" (interaction last status time),
  "customer": {
    "id"': "id" (customer id),
    "fields": { (each field can be an string or array (single/multiple fields))
    "channel_email": ["phone_1", "phone2"],
    "channel_external": "",
    "channel_facebook": "",
    "channel_mercado_livre": "",
    "channel_phone": "",
    "channel_telegram": "",
    "document": "",
    "main_identifier": "Example",
    "main_photo": ""
  }
  },
  "department": {
    "id": "department_id",
    "name": "department_name"
  },
  "id": "protocol",
  "media": "service channel",
Caso não tenha nenhum SLA pra interação, vai retornar "slas": []
Caso haja, vai retornar uma lista tipo essa:
"slas": [
{
"id": 888,
"sla_ended_at": "2023-10-03T13:00:17",
"sla_expired": false,
"sla_name": "sla_service_time",
"sla_started_at": "2023-10-03T13:00:00",
"sla_time": 120
},
{
"id": 886,
"sla_ended_at": "2023-10-03T13:00:00",
"sla_expired": true,
"sla_name": "sla_queued_time",
"sla_started_at": "2023-10-03T12:59:30",
"sla_time": 20
},
{
"id": 887,
"sla_ended_at": "2023-10-03T13:00:02",
"sla_expired": true,
"sla_name": "sla_first_reply_time",
"sla_started_at": "2023-10-03T12:59:30",
"sla_time": 30
},
{
"id": 889,
"sla_ended_at": "2023-10-03T13:00:13",
"sla_expired": false,
"sla_name": "sla_message_time",
"sla_started_at": "2023-10-03T13:00:10",
"sla_time": 10
}
]
  }]
}

Retorno de Erro:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

Como podemos ajudar?

TOKEN

CANAIS DIGITAIS

HISTÓRICO DE ATENDIMENTOS

HISTÓRICO DE CONVERSA

ATENDIMENTOS EM ANDAMENTO