A API Remota do Bot permite que você crie uma árvore de decisões totalmente personalizada para o Bot da OmniChat, integrada aos seus sistemas internos. Em vez de configurar o fluxo diretamente na plataforma, você define as respostas e encaminhamentos em uma API própria.
Como funciona o fluxo
O cliente entra em contato por qualquer canal integrado à loja
O Bot recebe a mensagem e apresenta as opções de atendimento
O cliente escolhe uma opção válida
Se a opção for do tipo
REMOTE_API_HANDLER, o Bot faz uma chamada para a sua API externaCom base na resposta da API, o Bot executa uma das seguintes ações:
Tipo de resposta | O que acontece |
| Redireciona o atendimento para o time especificado |
| Apresenta uma nova árvore de decisão ao cliente |
Erro (timeout, formato inválido, código HTTP de erro) | Encaminha para o time configurado em |
Estrutura enviada para a API externa
// Modelo (formato TypeScript)
interface Chat {
objectId: string; // id do canal (chat)
customerId?: string; // identificador único do cliente
phone?: string; // número do telefone
name?: string; // nome do cliente (se houver)
email?: string; // e-mail do cliente (se houver)
platform: string; // WHATSAPP, FBMESSENGER, WEBCHAT ou WAB
platformId?: string; // No caso do WAB/WHATSAPP, o número chamado
}interface BotRequest {
chat: Chat;
handlerId: string; // nome do estado
customerSupportRequestId: string; // identificador único do atendimento
}// Exemplo
{
"chat": {
"objectId": "IDENTIFICADOR_DA_CONVERSA",
"customerId": "IDENTIFICADOR_UNICO_DO_CLIENTE",
"phone": "NUMERO_DO_TELEFONE",
"name": "NOME_DO_CLIENTE",
"email": "EMAIL_DO_CLIENTE",
"platform": "WHATSAPP",
"platformId": "5541999999999"
},
"handlerId": "ID_ESTADO_SELECIONADO",
"botStateId": "ID_ESTADO_ATUAL",
"objectId": "IDENTIFICADOR_ÚNICO_DO_ATENDIMENTO"
}
Resposta com SEND_TO_TEAM
{
"handlerType": "SEND_TO_TEAM",
"handlerConfig": {
"teamId": "ID_DO_TIME",
"routingMessage": "Você está sendo redirecionado para o time XYZ"
}
}
Resposta com BOT_STATE_CHANGE_HANDLER
{
"handlerType": "BOT_STATE_CHANGE_HANDLER",
"toState": {
"title": "Para melhor atendê-lo, digite o número do setor desejado:",
"to": [
{
"title": "Cursos",
"handlerType": "SEND_TO_TEAM",
"index": 1,
"handlerConfig": {
"teamId": "ID_DO_TIME",
"routingMessage": "Você está sendo redirecionado para o setor Cursos."
}
},
{
"title": "Cursos Online",
"handlerType": "REMOTE_API_HANDLER",
"index": 2,
"handlerConfig": {
"botStateId": "QUESTAO_INICIAL",
"handlerId": "ONLINE_COURSES",
"url": "https://my.domain.com/url/to/service",
"fallbackTeam": "ID_DO_TIME"
}
}
]
}
}
Integrando com a API OmniChat e Webhooks
Além do bot customizado, você pode carregar e enviar dados da OmniChat usando:
API OmniChat: acesse ordens, times, usuários, chats e muito mais — documentação em api-docs.omni.chat
Webhooks: receba notificações em tempo real de alterações em objetos da OmniChat — veja o artigo de Webhooks para mais detalhes
Dica para desenvolvedores: Sempre configure um fallbackTeam nas integrações com API remota. Isso garante que o cliente nunca fique sem atendimento em caso de falha na sua API externa.