Documentação stoá.chat
Introdução
Autenticação
Entenda como autenticar suas requisições para utilizar a API da stoá.chat
Para uso da API deverá ser gerado um token permanente através da plataforma web da stoá.chat.
O token pode ser gerado acessando a página de integrações Ajustes > Integrações > Integração via API.
Após gerar o token, informe-o nos Headers de cada requisição, utilizando a chave Authorization e o schema Bearer.
Exemplo: Authorization: Bearer pn_0000000000000000000000.
Paginação
Entenda como a paginação nos endpoints de listagem funciona.
Vários endpoints de listagem de entidades possuem paginação, que é controlada através dos seguintes atributos pageNumber e pageSize, enviados no corpo da requisição.
JSON
{
"pageNumber": 1,
"pageSize": 50,
...
}
Sendo:
- pageNumber: indica qual página deseja obter;
- pageSize: indica o tamanho desta página, ou seja, quantos itens serão retornados, sendo possível no máximo 100.
Observe que ao alterar o pageSize em requisições subsequentes, o pageNumber retornará resultados diferentes. Portanto, é importante manter um pageSize constante enquanto se itera sobre o pageNumber.
Os resultados retornados nos endpoints paginados possuem a seguinte estrutura:
{
"pageNumber": 1,
"pageSize": 50,
"totalPages": 5,
"totalItems": 250,
"hasMorePages": true,
"items:" [{...}],
...
}
Sendo:
- pageNumber: indica qual página foi obtida;
- pageSize: indica o tamanho da página obtida;
- totalPages: total de páginas existentes para a consulta atual;
- totalItems: total de itens existentes para a consulta atual;
- hasMorePages: indica se há mais páginas a serem consultadas, ou seja, se pageNumber é menor que totalPages;
- items: array de entidades retornadas, cujo tamanho será menor ou igual a pageSize.
Rate Limiting
Existe um limite de 1000 requisições que você pode realizar a cada 5 minutos.
Requisições que ultrapassarem o limite possuirão como retorno o código de erro 429 - Too Many Requests.
Webhooks
Entenda como receber eventos da stoá.chat em outro sistema.
Configuração
O envio de eventos por webhook é um mecanismo para notificar o seu sistema quando uma variedade de interações ou eventos acontecem, incluindo quando uma pessoa envia uma mensagem ou um contato é alterado.
É possível realizar a configuração através da plataforma da Helena (acessando Ajustes > Integrações > Webhooks ) ou através de requisições para os endpoints de webhooks.
Ao criar uma nova assinatura, você deverá selecionar os eventos/tópicos que deseja assinar e informar uma URL válida. A Helena enviará requisições HTTP utilizando o método POST para a URL informada, que deverá estar preparada e disponível publicamente para receber os eventos.
É possível pausar temporariamente o recebimento de webhooks, modificando os status da assinatura para inativo.
Ciclo de uma conversa
Estrutura
As mensagens de webhook enviadas possuirão o corpo no formato application/json e a seguinte estrutura:
JSON
{
"eventType": "NOME_DO_EVENTO",
"date": "DATA_DE_ENVIO",
"content": { ... }
}
Sendo:
- eventType: o nome do evento/tópico, sendo os valores possíveis listados abaixo;
- date: data e hora de geração do evento na Helena, seguindo o formato YYYY-MM-DDTHH:mm:ss;
- content: conteúdo do evento.
Veja abaixo um exemplo de webhook de alteração de contato:
{
"eventType": "CONTACT_UPDATE",
"date": "2023-08-23T16:42:35.4359934Z",
"content": {
"id": "ed2b52f8-cf13-449b-b3d5-ae27051f4663",
"createdAt": "2022-10-28T21:24:26.158391Z",
"updatedAt": "2023-08-23T16:15:35.3814324Z",
"companyId": "626fb5de-0cc2-4209-b456-47b454ee6e14",
"name": "John Raymond Legrasse",
"phonenumber": "+55|00000000000",
"phonenumberFormatted": "(00) 00000-0000",
"email": "exemplo@email.com",
"instagram": null,
"annotation": "",
"tagsId": [],
"tags": [],
"status": "ACTIVE",
"origin": "CREATED_FROM_HUB",
"utm": null,
"customFieldValues": {},
"metadata": null
}
}
Webhook no Chatbot
Durante o atendimento pelo Chatbot, o sistema poderá disparar webhooks para buscar mais informações, dados e criar fluxos alternativos para uma melhor experiência dos clientes.
O webhook no chatbot tem uma mensagens de input e output padrões, você define a URL e recebe a mensagem via método POST.
Esta mensagem será enviada pelo chatbot para seu sistema com todos os dados capturados até o momento, os dados do canal de atendimento, dados do contato e as opções de respostas possíveis:
JSON
{
"responseKeys": [
"CLIENTE_EXISTE",
"CLIENTE_NAO_EXISTE"
],
"sessionId": "567ca9b8-eaa9-4a33-8cf9-d2c67060af74",
"channel": {
"id": "0a4ca3cd-b9fd-4523-a032-5a343bf7b209",
"key": "551140037752",
"platform": "WhatsApp",
"displayName": "(11) 4003-7752"
},
"contact": {
"id": "f8f43b22-2f20-42f3-be13-65bf90282143",
"name": "David",
"phonenumber": "+55|1199999999",
"display-phonenumber": "(11) 99999-9999",
"email": "email@gmail.com",
"instagram": null,
"tags": [
"Lead"
],
"cnpj": "00.000.000/0000-00",
"metadata": { "cod-ext": "abcd" }
},
"questions": {
"cb-ec36e3fe-qst-c0b0875a": {
"text": "Qual seu CNPJ?",
"answer": "00.000.000/0000-00"
}
},
"menus": {
"cb-ec36e3fe-mn-943b055a": {
"text": "Qual opção você deseja?",
"answer": "Comprar"
}
}
}
Seu webhook deverá responder com um código HTTP 200 para seguir no fluxo principal de sucesso, mas você poderá criar fluxos alternativos, assim deverá responder com o código HTTP 200 e uma mensagem conforme abaixo:
JSON
{
"response": "CLIENTE_EXISTE"
}
Você poderá atualizar os dados do contato no retorno do webhook, bem como metadados para serem usados em outro momento de integração, como no exemplo abaixo o código do cliente no seu sistema.
{
"response": "CLIENTE_EXISTE",
"metadata": {
"cliente-existe": true
},
"contact": {
"cnpj": "00.000.000/0000-00",
"metadata": {
"cod-ext": "abcd"
}
}
}
Também é possível enviar mensagens ao usuário ao retornar do webhook, você deverá indicar uma lista de mensagens que serão disparadas na ordem enviada;
{
"response": "CLIENTE_EXISTE",
"messages": [
{
"text": "Segue seu boleto abaixo para pagamento. Vencimento dia 10/01"
},
{
"fileUrl": "https://xyz.com/boleto.pdf"
},
{
"template": {
"id": "ab78cd_oferta",
"parameters": {
"valor": "R$ 9,99"
}
}
}
]
}
As mensagens podem incluir texto e/ou arquivo. Além disso, é possível utilizar um modelo de mensagem (template) previamente criado.
As opções de respostas foram separadas para efeitos didáticos, mas podem ser combinadas em uma única mensagem.
Alguma dúvida?
Entre em contato direto com o suporte
