API Channel

Introdução

O API Channel permite integrar sistemas externos com a plataforma através de uma API REST. É ideal para:

• Chatbots customizados
• Integração com sistemas legados
• Aplicações mobile ou web próprias
• Automações e integrações via webhook

Enviando Mensagens (Inbound)

Para enviar mensagens do cliente para a plataforma, faça um request do tipo POST:

  POST /webhooks/api

Mensagem de Texto

Campo	Tipo	Obrigatório	Descrição
channelId	string	✔️	ObjectId do canal
clientIdentifier	string	✔️	Identificador único do usuário
type	string	✔️	Tipo da mensagem ("text")
text	string	✔️	Conteúdo da mensagem

curl -X POST /webhooks/api \
  -H 'Content-Type: application/json' \
  --data '{
    "channelId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "clientIdentifier": "user-123",
    "type": "text",
    "text": "Olá, preciso de ajuda"
  }'

Exemplo de payload:

{
  "channelId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "clientIdentifier": "user-123",
  "type": "text",
  "text": "Olá, preciso de ajuda"
}

Resposta de Botões/Listas (Postback)

Quando o usuário seleciona uma opção de botão ou lista:

Campo	Tipo	Obrigatório	Descrição
channelId	string	✔️	ObjectId do canal
clientIdentifier	string	✔️	Identificador único do usuário
type	string	✔️	Tipo da mensagem ("text")
text	string	✔️	Texto da opção selecionada
postback	string	✔️	Identificador da opção

Formatos de postback

Formato	Descrição	Exemplo
indexN	Botão ou item de lista simples	"index0", "index1"
sectionN-indexM	Item de lista com seções	"section0-index1"

curl -X POST /webhooks/api \
  -H 'Content-Type: application/json' \
  --data '{
    "channelId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "clientIdentifier": "user-123",
    "type": "text",
    "text": "Opção selecionada",
    "postback": "index0"
  }'

Exemplo de payload:

{
  "channelId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "clientIdentifier": "user-123",
  "type": "text",
  "text": "Opção selecionada",
  "postback": "index0"
}

Eventos Recebidos no Webhook (Outbound)

Quando o bot envia uma mensagem, seu webhook recebe um POST com a seguinte estrutura:

Campo	Tipo	Descrição
contactId	string	ObjectId do contato
interactionId	string	ObjectId da interação
messages	array	Array de mensagens (geralmente 1)
debug	object\|null	Dados de debug (apenas em canais de teste)

Exemplo de payload recebido:

{
  "contactId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "interactionId": "64a1b2c3d4e5f6a7b8c9d0e2",
  "messages": [...],
  "debug": null
}

Tipos de Mensagem Outbound

Texto (type: "text")

Campo	Tipo	Descrição
type	string	"text"
text	string	Mensagem do bot
origin	string	Origem ("bot")
createdAt	string	Data de criação (ISO 8601)

{
  "type": "text",
  "text": "Mensagem do bot",
  "origin": "bot",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Data (type: "date")

Solicita que o usuário informe uma data.

Campo	Tipo	Descrição
type	string	"date"
text	string	Instrução para o usuário
origin	string	Origem ("bot")
createdAt	string	Data de criação (ISO 8601)

{
  "type": "date",
  "text": "Selecione uma data",
  "origin": "bot",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Botões (type: "buttons")

Campo	Tipo	Descrição
msgid	string	ID da mensagem
type	string	"buttons"
buttons	object	Objeto com texto e opções
origin	string	Origem ("bot")
createdAt	string	Data de criação (ISO 8601)

Estrutura do objeto buttons:

Campo	Tipo	Descrição
text	string	Texto da mensagem
options	array	Array de opções de botão

Estrutura de cada opção:

Campo	Tipo	Descrição
label	string	Texto exibido no botão
value	string	Valor do postback (indexN)

{
  "msgid": "64a1b2c3d4e5f6a7b8c9d0e3",
  "type": "buttons",
  "buttons": {
    "text": "Escolha uma opção:",
    "options": [
      { "label": "Opção 1", "value": "index0" },
      { "label": "Opção 2", "value": "index1" },
      { "label": "Opção 3", "value": "index2" }
    ]
  },
  "origin": "bot",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Lista (type: "list")

Lista simples (sem seções)

Campo	Tipo	Descrição
msgid	string	ID da mensagem
type	string	"list"
list	object	Objeto com texto e opções
origin	string	Origem ("bot")
createdAt	string	Data de criação (ISO 8601)

Estrutura do objeto list:

Campo	Tipo	Descrição
text	string	Texto da mensagem
title	string	Título do botão de ação
options	array	Array de seções/itens

Estrutura de cada item:

Campo	Tipo	Descrição
label	string	Texto do item
description	string	Descrição opcional
value	string	Valor do postback

Lista simples:

{
  "msgid": "64a1b2c3d4e5f6a7b8c9d0e3",
  "type": "list",
  "list": {
    "text": "Selecione um item:",
    "title": "Selecionar",
    "options": [
      {
        "items": [
          { "label": "Item 1", "description": "Descrição do item", "value": "index0" },
          { "label": "Item 2", "description": "", "value": "index1" }
        ]
      }
    ]
  },
  "origin": "bot",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Lista com seções:

{
  "msgid": "64a1b2c3d4e5f6a7b8c9d0e3",
  "type": "list",
  "list": {
    "text": "Selecione um item:",
    "title": "Selecionar",
    "options": [
      {
        "label": "Seção 1",
        "items": [
          { "label": "Item 1.1", "description": "", "value": "section0-index0" },
          { "label": "Item 1.2", "description": "", "value": "section0-index1" }
        ]
      },
      {
        "label": "Seção 2",
        "items": [
          { "label": "Item 2.1", "description": "", "value": "section1-index0" }
        ]
      }
    ]
  },
  "origin": "bot",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Mídia (type: "media")

Campo	Tipo	Descrição
type	string	"media"
media	object	Objeto com dados da mídia
origin	string	Origem ("bot")
createdAt	string	Data de criação (ISO 8601)

Estrutura do objeto media:

Campo	Tipo	Descrição
type	string	Tipo de mídia
link	string	URL do arquivo
filename	string	Nome do arquivo
text	string	Legenda opcional

Tipos de mídia suportados:

Tipo	Descrição
image	Imagem (PNG, JPG, etc.)
video	Vídeo
audio	Áudio
document	Documento (PDF, etc.)
sticker	Sticker

{
  "type": "media",
  "media": {
    "type": "image",
    "link": "https://example.com/imagem.png",
    "filename": "imagem.png",
    "text": "Legenda opcional"
  },
  "origin": "bot",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Resposta Esperada do Webhook

Seu webhook deve responder com status 200 e o seguinte body:

{
  "status": "ok"
}

Fluxo de Integração

┌─────────────┐                    ┌──────────────┐                    ┌─────────────┐
│   Cliente   │                    │ API SmartTalks│                    │ Seu Sistema │
└──────┬──────┘                    └──────┬───────┘                    └──────┬──────┘
       │                                  │                                   │
       │  1. Usuário envia mensagem       │                                   │
       │ ─────────────────────────────────>                                   │
       │  POST /webhooks/api              │                                   │
       │  {channelId, clientIdentifier,   │                                   │
       │   type: "text", text: "Olá"}     │                                   │
       │                                  │                                   │
       │                                  │  2. Bot processa e responde       │
       │                                  │ ──────────────────────────────────>
       │                                  │  POST (webhook configurado)       │
       │                                  │  {contactId, interactionId,       │
       │                                  │   messages: [{type: "buttons",    │
       │                                  │   buttons: {...}}]}               │
       │                                  │                                   │
       │                                  │  3. Webhook responde              │
       │                                  │ <──────────────────────────────────
       │                                  │  {status: "ok"}                   │
       │                                  │                                   │
       │  4. Usuário seleciona opção      │                                   │
       │ ─────────────────────────────────>                                   │
       │  POST /webhooks/api              │                                   │
       │  {channelId, clientIdentifier,   │                                   │
       │   type: "text", text: "Opção 1", │                                   │
       │   postback: "index0"}            │                                   │
       │                                  │                                   │
       │                                  │  5. Bot continua o fluxo          │
       │                                  │ ──────────────────────────────────>
       │                                  │  POST (webhook configurado)       │
       │                                  │  {messages: [{type: "text",       │
       │                                  │   text: "Você escolheu..."}]}     │
       │                                  │                                   │