Mensagens com 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, inclua um token de autenticação no cabeçalho da requisição:

Authorization: Bearer {SEU_TOKEN}

​

🌐 Base URL

Utilize {BASE_URL} para apontar ao ambiente adequado (por exemplo, produção em https://api.tolky.to).

​

⚙️ Parâmetros da Requisição

​

📋 Campos Principais

​

🔧 Estrutura do Objeto dentro do Array data

​

📦 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 {SEU_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

​

✅ Resultados Esperados

• Cada item de data é avaliado e, quando válido, recebe tentativas de envio conforme os canais habilitados (por exemplo, WhatsApp e/ou e-mail).
• O retorno contém results com o status agregado por item e um summary com totais processados.
• O campo processedItems pode detalhar por item o que foi considerado e os status de envio por canal.

​

🔒 Segurança

• Use sempre HTTPS e armazene o token de forma segura (variáveis de ambiente).
• Evite incluir dados sensíveis desnecessários em data e em generalInstructions.
• Não exponha tokens em aplicativos cliente. Prefira fazer chamadas pelo seu servidor.

​

🔄 Endpoints Relacionados

​

Tolky Reasoning

Para processamento de perguntas e respostas contextualizadas utilizando a inteligência do Tolky.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning

Ver documentação completa