Endpoint External Notification IA
Documentação completa da API que permite o disparo de mensagens com contexto personalizado e instruções específicas para processamento pela IA.
O endpoint External Notification IA permite o disparo de mensagens com contextualização personalizada, utilizando dados específicos fornecidos na requisição junto com instruções do gestor para guiar o processamento pela inteligência artificial.
📑 Índice
- 🎯 Visão Geral
- 🔑 Autenticação
- ⚙️ Parâmetros da Requisição
- 📦 Estrutura da Resposta
- 💡 Exemplos de Uso
- ⚠️ Tratamento de Erros
- ✨ Boas Práticas
- 🔄 Endpoints Relacionados
🎯 Visão Geral
O endpoint External Notification IA é responsável por:
🔑 Autenticação
Para utilizar o endpoint, é necessário incluir um token de autenticação no header da requisição:
Authorization: Bearer {seu-token-de-acesso}
⚙️ Parâmetros da Requisição
📋 Campos Principais
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
data | array | Sim | — | Array de objetos contendo informações para contextualização |
generalInstructions | string | Não | — | Instruções sobre como proceder com os dados disponíveis |
externalCampaignId | string | Não | null | Identificador de campanha externa para rastreio na base |
pauseConversation | boolean | Não | false | Define se a conversa será pausada após o disparo (IA não responderá caso o usuário retorne a conversa) |
🔧 Estrutura do Objeto dentro do Array data
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
id | string | Não | null | Identificador externo do usuário, para rastreio na base |
name | string | Não | null | Nome do usuário, melhora performance de rastreio na base, mas não impede o envio caso ausente |
phone | string | Sim | — | Número de telefone para envio da mensagem (formato E.164 recomendado) |
| Campos adicionais | — | Não | — | Quaisquer outras variáveis que poderão ser utilizadas para complementar o contexto da mensagem |
📦 Estrutura da Resposta
A resposta da API segue o formato padrão das APIs Tolky, com códigos de status e mensagens relevantes.
{
"code": 200,
"data": {
"results": [
{
"status": "fulfilled",
"value": {
"phone": "string",
"email": "string",
"whatsappStatus": "success",
"whatsappReason": null,
"emailStatus": "success",
"emailReason": null
}
}
],
"summary": {
"totalItems": 0,
"validItems": 0,
"skippedItems": 0,
"sentItems": 0,
"failedItems": 0
},
"processedItems": [
{
"originalData": {},
"processedData": {},
"status": "string",
"details": {
"phone": "string",
"email": "string",
"whatsappStatus": "string",
"whatsappReason": null,
"emailStatus": "string",
"emailReason": null
}
}
],
"error": null,
"time": 0
},
"message": "OK"
}
💡 Exemplos de Uso
Tab Title
Tab Title
curl --location '{base-url}/api/externalAPIs/public/externalNotificationAI' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {User-Access-Token}' \
--data-raw '{
"data": [
{
"id": "123"
"name": "Nome Exemplo",
"email": "exemplo@email.com",
"phone": "31999999991",
"city": "Cidade Exemplo",
"vehicle": "Modelo Exemplo"
},
{
"id": "1234"
"name": "Nome Exemplo 2",
"email": "exemplo2@email.com",
"phone": "31999999992",
"city": "Cidade Exemplo 2",
"vehicle": "Modelo Exemplo 2"
}
],
"generalInstructions": "Estamos enviando uma mensagem para uma campanha de promoção para a proteção veicular, preciso que engaje o usuário a comprar.",
"externalCampaignId": "0910",
"pauseConversation": false
}'
Exemplo com Múltiplos Destinatários
{
"data": [
{
"id": "123",
"phone": "31999999999",
"name": "João Silva",
"productInterest": "Sedan Luxo"
},
{
"id": "1234",
"phone": "31888888888",
"name": "Maria Santos",
"productInterest": "SUV Compacto"
}
],
"generalInstructions": "Enviar mensagens personalizadas sobre os veículos de interesse, destacando promoções atuais.",
"externalCampaignId": "0910",
"pauseConversation": false
}
⚠️ Tratamento de Erros
⏱️ Timeout
Todas as requisições têm um timeout de 60 segundos. Se a requisição exceder este limite, será retornado um erro 408 (Request Timeout).
✨ Boas Práticas
🔄 Endpoints Relacionados
Tolky Reasoning
Para processamento de perguntas e respostas contextualizadas utilizando a inteligência do Tolky.
Endpoint: POST /api/externalAPIs/public/tolkyReasoning