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
Quando usar API Channel
Seção intitulada “Quando usar API Channel”| Cenário | Use 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 |
Arquitetura
Seção intitulada “Arquitetura”┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐│ │ │ │ │ ││ 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 │└──────────────┘ └──────────────────┘ └─────────────────┘Pré-requisitos
Seção intitulada “Pré-requisitos”- 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
Passo a passo
Seção intitulada “Passo a passo”1. Criar inbox API Channel
Seção intitulada “1. Criar inbox API Channel”- Config. → Caixas de Entrada → Adicionar Caixa de Entrada.
- Selecione API.
- 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
- 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ê:
Criar contato (se ainda não existe)
Seção intitulada “Criar contato (se ainda não existe)”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.
Criar conversa
Seção intitulada “Criar conversa”curl -X POST "https://app.smart2.com.br/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/SOURCE_ID/conversations" \ -H "Content-Type: application/json" \ -d '{}'Enviar mensagem do cliente para o app.smart
Seção intitulada “Enviar mensagem do cliente para o app.smart”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, jsonifyimport 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 '', 200Quando agente envia mensagem no app.smart, sua webhook recebe e você entrega ao cliente no canal apropriado.
Casos de uso típicos
Seção intitulada “Casos de uso típicos”Chatbot independente
Seção intitulada “Chatbot independente”Você tem chatbot próprio que conversa com cliente. Quando o bot decide passar pra humano, cria conversa no app.smart e equipe assume.
App mobile com mensagens
Seção intitulada “App mobile com mensagens”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.
Discord / Slack como canal
Seção intitulada “Discord / Slack como canal”Bot do Discord na sua comunidade. Mensagem DM ao bot → repassa para app.smart → agente atende → resposta volta ao Discord.
Canal interno corporativo
Seção intitulada “Canal interno corporativo”Sistema legado de tickets internos. Funcionários abrem ticket → ticket vira conversa no app.smart → equipe atende com contexto unificado.
Configurações avançadas
Seção intitulada “Configurações avançadas”
Para enviar anexo do cliente:
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"Identificar tipo de evento
Seção intitulada “Identificar tipo de evento”Webhook outbound recebe vários eventos, não só mensagens. Filtre por event:
message_createdconversation_createdconversation_status_changedcontact_updated
Custom attributes via API
Seção intitulada “Custom attributes via API”Atualizar atributos personalizados do contato:
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.
Limitações
Seção intitulada “Limitações”- 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_windownos 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
Segurança
Seção intitulada “Segurança”- Sempre valide HMAC em webhooks recebidos do app.smart
- Não exponha
INBOX_IDENTIFIERou tokens em frontend - Use HTTPS em todos os endpoints
- Rate limit seu sistema para não ser usado como DoS contra o app.smart
Dúvidas comuns
Seção intitulada “Dúvidas comuns”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.