Como funciona a API de conversas?
KS
Escrito por Ketelyn S
atualizado
Quem utilizar nossa API de conversas e não sabe como? Vem com a gente que vamos te contar tudo. o/
Por que utilizar a API de conversas?
Mais autonomia: Gerencie a criação de Tokens direto pelo seu Octadesk! Crie, ative, desative e exclua Tokens de acordo com a sua necessidade;
Mais segurança: Envie em cada requisição, além do seu Token privado, o e-mail do usuário responsável pelas requisições, garantindo maior controle e rastreabilidade
Mais facilidade: Cada página da documentação vem com uma série de dicas sobre como utilizá-la e quais regras devem ser atendidas.
Acesse nossa API de conversas clicando aqui.
Quando utilizar as novas API's da Octadesk?
Além de conseguir consultar dados sobre os “Contatos” e enviar mensagens de WhatsApp automaticamente, é possível realizar a consulta de diferentes informações sobre as “Conversas” no Octadesk! Um recurso muito esperado por nossos clientes que automatizam diferentes análises e processos em seu dia-a-dia.
Com as API’s de “Conversas” no Octadesk é possível:
1 - Consultar dados de uma conversa através do seu ID;
2 - Consultar o histórico de mensagens trocadas em uma conversa através do seu ID;
3 - Consultar e extrair o histórico completo de conversas do seu Octadesk.
As consultas viabilizam diferentes integrações com outros softwares que a sua empresa utiliza, garantindo uma maior confiabilidade dos dados, rapidez na execução de tarefas rotineiras, aumento na eficiência operacional do time e diminuição do volume de atendimentos.
Exemplos de utilização das API’s Octadesk:
Cenário 1: Levando o histórico da conversa para a Oportunidade no CRM de Vendas.
Se você utiliza um CRM que te permite fazer requisições em diferentes API’s ou usa uma plataforma de integração como o Zapier ou o Pluga, é possível consultar os dados de uma conversa de forma simples, apenas utilizando o ID da conversa.
Toda conversa possui um ID na composição de sua URL, este ID se chama RoomKey e é ele que utilizaremos para realizar a consulta via API, por exemplo:
Sabendo o ID, é possível realizar a consulta utilizando o seguinte caminho:
Esse caminho requer as seguintes informações:
GERAR X-API-KEY:
O X-API-KEY é a chave de autorização para que seja possível consultar dados do seu Octadesk por API. Não a compartilhe com ninguém por questões de segurança! Para gerá-lo, vá até o menu "Configurações" > "WhatsApp API" > "Gerar apiKey".
GERAR Base URL:
É o endereço que receberá as requisições, ele é composto pelo seu subdomínio e informações privadas do seu Octadesk, aumentando sua segurança e controle sobre as interações realizadas. Para acessá-la, desça até o fim da página onde o X-API-KEy foi gerado, no menu "Configurações" > "WhatsApp API" > "Base URL".
Em seguida, ajuste a requisição abaixo, preenchendo com seus dados os campos ‘X-API-KEY’ e 'octa-agent-email’:
curl --request GET \
--url (COLOQUE A SUA URL BASE AQUI, COPIANDO ATÉ A BARRA DO CHAT, ADICIONE UMA BARRA E COLE O ID (ROOMKEY) DA CONVERSA DESEJADA) \
--header 'X-API-KEY: COLOQUE A SUA X-API-KEY AQUI' \
--header 'accept: application/json' \
--header 'octa-agent-email: coloque o seu e-mail do Octadesk aqui'
Exemplo:
curl --request GET \
--url https://subdomínio.informaçãodoambiente.octadesk.services/chat/IDDACONVERSA \
--header 'X-API-KEY: coloque sua X-API-KEY aqui' \
--header 'accept: application/json' \
--header 'octa-agent-email: coloque o seu e-mail do Octadesk aqui'
Dica da Octadesk:
O Postman é uma plataforma muito utilizada para realizar testes em API’s, faça o download
clicando aqui. Depois de instalá-lo clique em “Import” e cole a requisição com seus dados preenchidos:
Para executar, clique no botão "Send":
Após clicar em “Send” no Postman, na janela logo abaixo será apresentado o resultado da execução da chamada da API. Se atenha sempre ao resultado de sucesso que corresponde ao código 200, caso o código seja diferente de 200, verifique se o os dados da requisição estão corretos.
Exemplo do código 200 sendo mostrado na parte superior da API de resposta:
O retorno da requisição será algo parecido com isso:
{
"id": "99f2b32a-6f0e-4755-840d-a6ac508864e0",
"number": 2401128000,
"createdAt": "2024-01-12T18:42:43.509Z",
"updatedAt": "2024-01-12T18:45:12.422Z",
"channel": "whatsapp",
"contact": {
"id": "edddb8c6-e6f9-48fd-add9-ae1c1467270a",
"name": "Octávio da Octadesk",
"email": "octavio@octadesk.com"
},
"agents": [
{
"id": "1b7e02e7-94e9-4df0-88b4-b284afcf9900",
"name": "Atendente",
"email": "email@dominio.com"
}
],
"messages": [
{
"id": "c5a92e83-1324-484e-859f-65043ec68b17",
"chatId": "99f2b32a-6f0e-4755-840d-a6ac508864e4",
"time": "2024-01-12T18:42:43.475Z",
"type": "public",
"body": "Olá, tudo bem?",
"readAt": "2024-01-12T18:44:10.507Z",
"attachments": [
{
"id": "65a9309f4ac02000073fc1d7",
"name": "nome-do-anexo",
}
],
"sentBy": {
"id": "1b7e02e7-94e9-4df0-88b4-b284afcf9915",
"name": "Atendente",
"email": "email@dominio.com",
"type": "agent"
},
"status": "read"
},
{
"id": "5155f5a4-182b-3e56-9b3d-8eca3f6b5060",
"chatId": "99f2b32a-6f0e-4755-840d-a6ac508864e4",
"time": "2024-01-12T18:44:09.000Z",
"type": "public",
"body": "Bem e você?",
"readAt": "2024-01-12T18:44:10.424Z",
"sentBy": {
"id": "edddb8c6-e6f9-48fd-add9-ae1c1467279a",
"name": "Octávio da Octadesk",
"email": "octavio@octadesk.com",
"type": "contact"
},
"status": "received"
}
],
"lastMessageDate": "2024-01-12T18:44:09.000Z",
"firstMessageDate": "2024-01-12T18:42:43.475Z",
"messagesCount": 2,
"status": "talking",
"waitingTime": 0,
"tags": [
{
"id": "6542524e0c4f14000775da80",
"name": "Dúvida"
}
],
"windowExpiresAt": "2024-01-13T18:43:00.000Z",
"withBot": false,
"unreadMessages": true
}
Não se preocupe, é bastante informação. Mas, para ajudá-lo, criamos um dicionário que descreve cada elemento do retorno da requisição. Isso auxiliará a identificar quais propriedades são relevantes para sua integração:
Agora é só escolher quais dessas informações você quer armazenar em seu CRM e preencher os campos responsáveis por armazená-las.
Mais dicas da Octadesk:
1 - As propriedades de mensagens (messages) podem ser armazenadas nas áreas de observações/anotações do seu CRM para que seja simples de consultá-las. Um exemplo muito bom e prático é o
Hubspote esse endpoint que permite cadastrar uma conversa de WhatsApp;
2 - Já as propriedades “fixas” da conversa como Tempo de espera, Responsável, ID da conversa, Tags, dentre outras, podem ser armazenadas no Contato ou em propriedades de conversa, caso seu CRM contemple isso, desta forma seus relatórios serão muito mais personalizados;
3 - O ID da conversa pode ser enviado via API para o seu CRM no começo da conversa usando as Superintegrações do nosso Bot, facilitando a construção dessa integração!
Saiba mais aqui;
4 - Caso seja necessário consultar apenas as mensagens das conversas, existe um endpoint específico para isso, assim, fica mais fácil de tratar o dado da maneira que desejar.
Saiba mais aqui.
Cenário 2 - Consultando o histórico completo de conversas do Seu Octadesk para integrá-lo à plataformas de BI.
Sabendo que diferentes plataformas de BI ou construtores de relatórios fazem o uso da base histórica de dados, a Octadesk desenvolveu um endpoint que permite a consulta de todas as conversas por meio de diferentes tipos de filtros. Vamos nos aprofundar um pouco mais em como utilizá-la a partir de agora.
A estrutura da requisição é semelhante à anterior, vamos usar tanto o X-API-KEY quanto a Base URL, porém, o caminho é esse aqui:
A diferença do endpoint que consulta as conversas via ID para este, é que existe a possibilidade de filtrar a consulta por meio de propriedades e a resposta dessa requisição trará várias conversas de uma única vez, se seus filtros forem configurados para que isso aconteça.
Vamos à prática:
O que são filtros?
São parâmetros que podem ser utilizados em sua requisição para definir quais resultados ela deverá retornar e neste link há uma explicação bem detalhada sobre as opções disponíveis. Para ilustrar, vamos trazer alguns exemplos aqui:
Informação textual da imagem acima:
Propriedade: number
Formato: number
Descrição: ID numérico da conversa
Propriedade: createdAt
Formato: date
Descrição: Data de criação da conversa
Propriedade: updatedAt
Formato: date
Descrição: Data da última atualização da conversa
Propriedade: channel
Formato: string
Descrição: Canal de origem da conversa
Propriedade: phoneContacts.number
Formato: string
Descrição: Número de telefone associado ao contato
Propriedade: contact.name
Formato: string
Descrição: Nome do contato
Propriedade: contact.email
Formato: string
Descrição: E-mail do contato
Propriedade: status
Formato: string
Descrição: Status da conversa
Propriedade: withBot
Formato: boolean
Descrição: Se a conversa está sendo atendida por um Bot ou não
Propriedade: group.id
Formato: string
Descrição: ID do Grupo atribuído como responsável pela conversa
Propriedade: agent.id
Formato: string
Descrição: IID do Responsável pela conversaVeja como é simples de montar uma consulta com filtro, neste caso o objetivo é construir a consulta que retorne apenas conversas criadas após uma data específica:
curl --request GET \
--url https://subdomínio.informaçãodoambiente.octadesk.services/chat?filters[0][operator]=gt&filters[0][property]=createdAt&filters[0][value]=2024-01-21T00:00:00.001Z \
--header 'X-API-KEY: coloque sua X-API-KEY aqui' \
--header 'accept: application/json' \
--header 'octa-agent-email: coloque o seu e-mail do Octadesk aqui'
Note que, logo após a Base URL, foi colocada uma interrogação “?” e uma série de elementos. Vamos detalhar cada um deles a seguir.
1 - Interrogação: A interrogação indica que parâmetros serão incluídos na requisição, logo, ele é um caractere especial que indica mais elementos que a requisição deve considerar para realização do filtro;
2 - filters[0]: O número zero (0) indica que esse é o primeiro filtro realizado na requisição, ou seja, se outros filtros forem incluídos, eles seguirão o mesmo padrão, sequencialmente, ou seja, incrementando de 1 em 1, por exemplo: filters[1], filters[2], filters[3];
3 - [operator]=gt&: O termo “operator” indica como esse filtro vai funcionar e o termo “=gt” significa “Greater Than”, ou seja, maior que (>).
Existem vários operadores que podem ser utilizados, nesse link listamos todos eles. No final do texto existe um “&”, um concatenador, indica uma continuação na inclusão de parâmetros;
4 - filters[0][property]=createdAt&: Todo filtro obrigatoriamente deve ter um Operador (operator), uma Propriedade (property) e um Valor (value). Logo, na instrução filters[0][operator]=gt&filters[0][property]=createdAt, significa que o primeiro filtro terá como condição recuperar todas as conversas com o atributo createdAt MAIOR que, faltando somente informar qual valor de referência;
5 – filters[0][value]=2024-01-01T00:00:00.001Z: A data de referência para consulta é 01/01/2024 e hora 00:00:00:0001 (o primeiro milissegundo do dia).
Ou seja, filters[0][operator]=gt&filters[0][property]=createdAt&filters[0][value]=2024-01-01T00:00:00.001Z significa, listar todas conversas que a data de criação seja maior que 01/01/2024 e hora 00:00:00:0001.
Para executar, no Postman, você vai informar a sua requisição com o filtro acima e clicar em "Send", o retorno dessa requisição será algo parecido com:
[
{
"id": "bb7f8450-da82-4a4d-a339-afcc44fb95300",
"number": 2401188521,
"channel": "whatsapp",
"contact": {
"id": "edddb8c6-e6f9-48fd-add9-ae1c1467279a0",
"name": "Artur Mendes"
},
"agent": {
"id": "1b7e02e7-94e9-4df0-88b4-b284afcf99150",
"name": "Artur Mendes",
"email": "email@dominio.com"
},
"lastMessageDate": "2024-01-18T19:26:11.740Z",
"status": "talking",
"tags": [],
"withBot": false,
"unreadMessages": false,
"createdAt": "2024-01-18T19:24:11.731Z",
"updatedAt": "2024-01-18T19:26:14.452Z"
},
{
"id": "219cc78f-429d-4d47-9f69-9381a4844eee0",
"number": 2401188520,
"channel": "whatsapp",
"contact": {
"id": "edddb8c6-e6f9-48fd-add9-ae1c1467279a0",
"name": "Artur Mendes"
},
"agent": {
"id": "1b7e02e7-94e9-4df0-88b4-b284afcf9915",
"name": "Artur Mendes",
"email": ""email@dominio.com"
},
"lastMessageDate": "2024-01-18T19:24:11.785Z",
"status": "closed",
"tags": [],
"withBot": true,
"unreadMessages": false,
"createdAt": "2024-01-18T19:23:26.350Z",
"updatedAt": "2024-01-18T19:24:12.941Z"
}
]
Caso você deseje ordenar os resultados da consulta, use o & para complementar o filtro, com a ordem/direction (crescente - asc ou decrescente – desc) e a propriedade que será usada na classificação, por exemplo:&sort[direction]=desc&sort[property]=createdAt.
1 - sort[direction]=desc&: Indica que a ordenação é decrescente;
2 - sort[property]=createdAt: E que a propriedade referência da ordenação será a data de criação da conversa.
Pontos importantes:
1 - Quando não for informada uma data nos filtros das requisições que fará a busca, serão listadas as conversas criadas há 1 (um) mês;
2 - Os filtros de data não podem ser superiores há 1 (um) ano.
🐙 Dica do polvo 🐙