Pular para o conteúdo

Conectar API Channel

API Channel é um tipo de inbox personalizado para você integrar qualquer canal que não tenha conector nativo no app.smart — chatbot próprio, app mobile da sua empresa, Discord, sistema interno, etc.

Você implementa dois lados da integração:

  • Outbound — webhook que app.smart chama quando agente envia mensagem
  • Inbound — você chama API do app.smart quando cliente envia mensagem
CenárioUse API Channel?
Conectar canal sem suporte nativo (Discord, Slack DM, app próprio)✅
Construir chatbot customizado independente do Brain✅
Integrar com sistema de tickets legado✅
Migrar histórico de outro CRM para o app.smart⚠️ Use importação batch
Conectar WhatsApp ou Email❌ Use inbox nativo
Integrar com plataforma já suportada❌ Use a integração nativa
┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Cliente │ │ Seu sistema │ │ app.smart │
│ (no seu │ │ (broker) │ │ │
│ app/site) │ │ │ │ │
│ │ msg │ │ POST │ │
│ ├─────────►│ Recebe ├────────►│ /messages │
│ │ │ → repassa │ │ │
│ │ │ │ │ conversa │
│ │ │ │ │ fica visível │
│ │ │ │ │ pro agente │
│ │ │ │ │ │
│ │ │ │ │ Agente │
│ │ msg │ Webhook │ │ responde │
│ │◄─────────┤ recebido ├◄────────┤ │
│ │ │ → entrega ao │ │ POST │
│ │ │ cliente │ │ webhook │
└──────────────┘ └──────────────────┘ └─────────────────┘
  • Servidor backend próprio que aceita requisições HTTP
  • Endpoint público HTTPS acessível ao app.smart
  • Capacidade de fazer chamadas HTTP outbound (para app.smart)
  • Token de API do app.smart
  1. Config. → Caixas de Entrada → Adicionar Caixa de Entrada.
  2. Selecione API.
  3. O formulário pede dois campos:
    • Nome do Canal — ex.: “App Mobile Suaempresa”
    • URL do Webhook — o endereço do seu sistema que vai receber o que o agente responder
  4. Salve.

App.smart gera:

  • Inbox ID (você usa nas chamadas API)
  • API Inbox Identifier (chave pública)
  • HMAC Signing Token (para autenticar webhooks que app.smart enviar)

2. Implementar lado inbound (cliente → app.smart)

Seção intitulada “2. Implementar lado inbound (cliente → app.smart)”

Quando cliente envia mensagem no seu sistema, você:

Terminal window
curl -X POST "https://app.smart2.com.br/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts" \
-H "Content-Type: application/json" \
-d '{
"identifier": "MEU-APP-USER-123",
"name": "Maria Silva",
"email": "[email protected]",
"phone_number": "+5511999990000"
}'

Retorna source_id que você usa na criação de conversa.

Terminal window
curl -X POST "https://app.smart2.com.br/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/SOURCE_ID/conversations" \
-H "Content-Type: application/json" \
-d '{}'
Terminal window
curl -X POST "https://app.smart2.com.br/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/SOURCE_ID/conversations/CONV_ID/messages" \
-H "Content-Type: application/json" \
-d '{
"content": "Olá, tenho uma dúvida sobre o produto X",
"echo_id": "MSG_INTERNAL_ID_123"
}'

Mensagem aparece na caixa de entrada do app.smart com aviso para o agente.

3. Implementar lado outbound (app.smart → cliente)

Seção intitulada “3. Implementar lado outbound (app.smart → cliente)”

Configure seu servidor para aceitar POST na webhook URL configurada:

from flask import Flask, request, jsonify
import hmac, hashlib
app = Flask(__name__)
HMAC_TOKEN = "seu-hmac-token-do-inbox"
@app.post('/webhook/smart-outbound')
def outbound():
# Validar HMAC
signature = request.headers.get('X-Smart-Signature', '')
payload = request.get_data()
expected = hmac.new(HMAC_TOKEN.encode(), payload, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
return '', 401
event = request.json
if event['event'] == 'message_created':
msg = event['message']
# Filtrar: só mensagens enviadas (outgoing) e não privadas
if msg['message_type'] == 'outgoing' and not msg['private']:
# Entregar ao cliente no seu sistema
external_user_id = event['contact']['identifier']
send_to_my_app(
user_id=external_user_id,
content=msg['content'],
attachments=msg.get('attachments', [])
)
return '', 200

Quando agente envia mensagem no app.smart, sua webhook recebe e você entrega ao cliente no canal apropriado.

Você tem chatbot próprio que conversa com cliente. Quando o bot decide passar pra humano, cria conversa no app.smart e equipe assume.

Seu app mobile tem aba “Fale com a empresa”. Cliente envia mensagem → app chama API do app.smart → agente vê e responde → resposta volta ao app via webhook.

Bot do Discord na sua comunidade. Mensagem DM ao bot → repassa para app.smart → agente atende → resposta volta ao Discord.

Sistema legado de tickets internos. Funcionários abrem ticket → ticket vira conversa no app.smart → equipe atende com contexto unificado.

Conectar API Channel: a aba Configurações da caixa de API, com o identificador e a URL de webhook

Para enviar anexo do cliente:

Terminal window
curl -X POST "https://app.smart2.com.br/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/SOURCE_ID/conversations/CONV_ID/messages" \
-F "content=Veja o arquivo" \
-F "attachments[]=@/path/to/file.pdf"

Webhook outbound recebe vários eventos, não só mensagens. Filtre por event:

  • message_created
  • conversation_created
  • conversation_status_changed
  • contact_updated

Atualizar atributos personalizados do contato:

Terminal window
curl -X PATCH "https://app.smart2.com.br/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/SOURCE_ID" \
-d '{
"custom_attributes": {
"plano_atual": "premium",
"valor_pedido": 350.00
}
}'

Agente vê esses atributos na sidebar da conversa, ajuda no atendimento.

  • Você é responsável pela entrega. Se o seu sistema cai, o que o agente responder não chega a ninguém
  • A janela de conversa existe, mas é opcional. Por padrão não há prazo: o agente escreve quando quiser. Dá para definir um, gravando um agent_reply_time_window nos atributos adicionais do canal — só que isso não tem campo na tela, vai pela API
  • CSAT não se replica sozinho. A pesquisa sai do lado do app.smart; mostrá-la ao cliente no seu sistema é trabalho seu
  • Sempre valide HMAC em webhooks recebidos do app.smart
  • Não exponha INBOX_IDENTIFIER ou tokens em frontend
  • Use HTTPS em todos os endpoints
  • Rate limit seu sistema para não ser usado como DoS contra o app.smart

Cliente final precisa ter conta no app.smart? Não. O cliente é representado por identifier (seu user ID). O app.smart trata como contato interno.

Posso ter vários inboxes API Channel diferentes? Sim. Um por canal/sistema integrado.

API Channel funciona com Brain (IA)? Sim. Você pode conectar Brain ao inbox API Channel — Brain responde como em qualquer outro canal.

Posso usar API Channel para enviar campanhas em massa? Sim, programaticamente. Mas considere Broadcasts que é nativo e mais simples para esse caso.