Configurando um canal via API
Visão Geral
Este guia descreve o procedimento técnico para criar, configurar e utilizar uma caixa de entrada do Canal API na
plataforma Solcon.
O Canal API permite que aplicações externas enviem e recebam mensagens diretamente através do ambiente Solcon,
possibilitando integrações personalizadas e fluxos de comunicação sob medida.
Criando a Caixa de Entrada do Canal API
1. Acessar Configurações
Entre no painel administrativo da Solcon.
Abra o menu: Configurações → Canais→ Adicionar canal.
2. Selecionar o Tipo “API”
Clique sobre o ícone referente ao Canal API para iniciar a configuração.
Criar e Configurar um Canal API
3. Definir Dados da Caixa de Entrada
Informe os seguintes campos:
- Nome da Caixa de Entrada: escolha um nome interno que facilite sua identificação.
- URL de Callback (Retorno): endereço que receberá notificações sempre que ocorrerem eventos no canal.
Exemplo de URL de callback:
https://suaaplicacao.com.br/webhook/solcon
4. Adicionar Agentes
Adicione os agentes responsáveis pelo atendimento dentro desse canal.
Após esta etapa o Canal via API estará criado e em funcionamento.
Estrutura de Comunicação do Canal API
Para utilizar o Canal API de forma apropriada, é fundamental entender os conceitos básicos da Solcon:
1. Canal: tipo de origem da conversa (API, WhatsApp, Facebook, etc.).
2. Caixa de Entrada: unidade de origem configurada. É possível ter múltiplas caixas de entrada do mesmo tipo.
3. Conversa: conjunto organizado de mensagens entre contato e agentes.
4. Contato: usuário final vinculado à conversa.
5. Contato-Inbox (contact_inbox): sessão de um contato dentro de uma caixa de entrada. Um mesmo contato pode possuir
várias sessões e conversas.
Envio de Mensagens pelo Canal API
O envio de mensagens ocorre em três etapas sequenciais:
1. Criar um Contato
Use a API de criação de contato informando:
- ID da Caixa de Entrada API
- Dados do contato (nome, e-mail, telefone, etc.)
Isso gera automaticamente uma sessão (contact_inbox).
A resposta inclui um source_id, que identifica esta sessão e será necessário para os próximos passos.
{
"id": 0,
"name": "string",
"contact_inboxes": [
{
"source_id": "string"
}
]
}
2. Criar uma Conversa
Envie uma requisição usando o source_id obtido no passo anterior.
A resposta fornecerá o conversation_id, necessário para enviar mensagens.
{
"id": 0
}
3. Enviar uma Mensagem
Utilize o conversation_id para enviar uma mensagem do tipo:
- incoming (recebida, enviada pelo usuário final)
- outgoing (enviada pelo agente)
{
"id": 0,
"content": "Mensagem recebida via Canal API",
"inbox_id": 0,
"conversation_id": 0,
"message_type": 0,
"sender": {
"id": 0,
"name": "Nome do Contato",
"type": "contact"
}
}
Se tudo estiver correto, a mensagem aparecerá imediatamente no painel da Solcon.
Recebendo Mensagens via URL de Callback
Sempre que uma nova mensagem for criada nesta caixa de entrada, sua aplicação receberá uma requisição POST no URL de
callback definido na criação do canal.
1. Estrutura do Evento
O tipo de evento é: message_created
{
"id": 0,
"content": "Mensagem recebida via Canal API",
"created_at": "2024-08-30T15:43:04.000Z",
"message_type": "incoming",
"sender": {
"id": 0,
"name": "contact-name",
"type": "contact"
},
"inbox": {
"id": 0,
"name": "API Channel"
},
"conversation": {
"id": 0,
"status": "open"
},
"account": {
"id": 1,
"name": "API Integration"
},
"event": "message_created"
}
Construindo Interfaces com as APIs de Cliente
A Solcon disponibiliza APIs voltadas para a criação de interfaces customizadas, permitindo:
- Interfaces próprias de chat (sem usar o widget padrão)
- Interfaces em aplicativos mobile
- Integrações com plataformas sem SDK oficial
1. Identificadores Importantes
- inbox_identifier: localizado em Configurações → Caixa de Entrada → Configuração.
- customer_identifier (source_id): obtido ao criar o contato.
Esse identificador deve ser armazenado no cliente (cookies, localStorage etc.).
Autenticação HMAC
As APIs de cliente podem usar HMAC para autenticação avançada.
O token HMAC pode ser obtido no console Rails:
As APIs de cliente podem usar HMAC para autenticação avançada.
O token HMAC pode ser obtido no console Rails:
# Substitua api_inbox_id pelo ID da sua caixa de entrada
Inbox.find(api_inbox_id).channel.hmac_token
Conexão com Solcon via WebSocket
Para receber notificações em tempo real no painel do agente, conecte-se ao WebSocket:
<sua-instancia-solcon>/cable
Inscreva-se:
const connection = new WebSocket('ws://localhost:3000/cable');
connection.send(JSON.stringify({
command: "subscribe",
identifier: "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"" + customer_pubsub_token + "\"}"
}));
A autenticação é feita usando o pubsub_token, fornecido na criação do objeto cliente na API.