Chat API

API para gerenciamento de atendimentos, mensagens e recursos de comunicação omnichannel

A Chat API é o módulo de mensageria e atendimento digital da plataforma omnichannel, projetado para orquestrar conversas entre empresas e clientes em múltiplos canais (como WhatsApp, Webchat, Instagram, Facebook, Telegram, entre outros), centralizando o fluxo de mensagens, atendimentos humanos e automações em uma única camada de integração.

Por meio da Chat API, aplicações externas podem iniciar e controlar atendimentos, enviar e receber mensagens, gerenciar contatos e usuários, consultar históricos e integrar fluxos de automação. A API foi construída para suportar operações em tempo real, alto volume de mensagens e cenários complexos de roteamento de atendimento, servindo como base para CRMs conversacionais, plataformas de suporte, vendas e automação de relacionamento com clientes.

A API se integra aos demais módulos da plataforma (como Voice, BSP e IA), permitindo a construção de experiências omnichannel completas, onde diferentes canais e modos de interação compartilham o mesmo contexto de atendimento e dados do cliente.

Visão Geral

• Padrão OpenAPI 3.0.0.

• Foco: Atendimentos, mensagens, contatos e gestão de agentes em ambiente omnichannel

• Integração nativa com módulos de voz, canais oficiais (BSP) e IA

• Formatos aceitos:

  • application/json

  • multipart/form-data (para envio de mídias, quando aplicável)

Base URL

• Base Path: https://{host}/api/v4

• O host varia por ambiente

Autenticação

A Chat API utiliza Bearer Token (JWT) para autenticação:

Authorization: Bearer {SEU_TOKEN}

Os tokens carregam o contexto de permissão do usuário autenticado, e a API diferencia dois perfis principais de uso, que impactam diretamente quais endpoints podem ser acessados:

Token de Agente

Utilizado para operações relacionadas ao atendimento operacional, como:

• Listar e assumir atendimentos

• Enviar e receber mensagens

• Consultar contatos vinculados ao atendimento

• Atualizar status do atendimento

• Interagir com recursos do dia a dia do agente

Esse tipo de token está sujeito às permissões do agente (equipes, filas, horários, etc.).

Token Administrativo

Utilizado para operações de configuração e gestão da plataforma, como:

• Cadastro e gerenciamento de agentes e equipes

• Configuração de canais de atendimento

• Gerenciamento de horários, pausas e tabulações

• Criação de templates de mensagens

• Configuração de integrações, webhooks e parâmetros globais

Alguns endpoints são exclusivos para tokens administrativos e retornarão erro de autorização quando acessados com token de agente.

Principais recursos

A Chat API expõe os principais domínios funcionais da plataforma de atendimento:

Gestão de Atendimentos

• Início, aceite, transferência e finalização de atendimentos

• Consulta de atendimentos ativos e históricos

• Encaminhamento entre equipes ou agentes

• Controle de status (em atendimento, em espera, finalizado, etc.)

• Suporte a múltiplos atendimentos simultâneos por agente

Objetivo: permitir que sistemas externos orquestrem todo o ciclo de vida de um atendimento.

Mensagens Omnichannel

• Envio e recebimento de mensagens em múltiplos canais

• Suporte a texto e mídias (quando suportado pelo canal)

• Mensagens ativas (outbound) e reativas (inbound)

• Templates e mensagens predefinidas

Objetivo: centralizar a camada de mensageria independentemente do canal de origem.

Contatos e Identidade do Cliente

• Criação e atualização de contatos

• Consulta por identificadores (telefone, e-mail, IDs externos)

• Campos personalizados por contato

• Associação de contatos a atendimentos e histórico de conversas

Objetivo: manter uma visão unificada do cliente ao longo de todos os canais e atendimentos.

Gestão de Agentes e Equipes

• Cadastro e manutenção de agentes

• Associação de agentes a equipes

• Configuração de horários, pausas e disponibilidade

• Definição de regras de roteamento e distribuição de atendimentos

Objetivo: controlar a operação humana de atendimento e o balanceamento de carga entre equipes.

Fluxos

• Integração com fluxos automatizados (bots, triagens, URAs digitais)

• Encaminhamento automático de atendimentos para agentes humanos

• Classificação e enriquecimento de mensagens via IA

• Apoio a cenários híbridos (bot + humano)

Objetivo: reduzir esforço manual e escalar o atendimento sem perder contexto.

Exemplos rápidos

Envio de mensagem de texto pelo agente:

curl -X POST "https://{host}/api/v4/message/send" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_id": "WhatsappBusiness",
    "channel_id": "channel_123",
    "type": "text",
    "message": "Olá! Como posso te ajudar hoje?"
  }'

Códigos de resposta comuns

Os endpoints retornam códigos HTTP padrão. A spec OpenAPI define os códigos e schemas por operação.

Boas práticas

• Definir Content-Type: application/json em requisições com corpo JSON.

• Para uploads, usar multipart/form-data quando o endpoint exigir arquivo.