Canais Personalizados #

Conecte qualquer plataforma de mensagens ou ferramenta de comunicação à plataforma usando canais personalizados. Isso permite que você traga mensagens de plataformas como widgets de chat ao vivo em sites, sistemas de e-mail, CRMs ou qualquer outro serviço para sua caixa de entrada — e responda a elas com seu Agente de IA.

O que são Canais Personalizados? #

Canais personalizados estendem a plataforma além de suas plataformas de mensagens integradas (WhatsApp, SMS, Instagram, Messenger). Com canais personalizados, você pode:

• Receber mensagens de qualquer plataforma externa na caixa de entrada unificada da plataforma.
• Enviar respostas do aplicativo de volta para sua plataforma externa automaticamente.
• Usar um Agente de IA para responder a mensagens de qualquer fonte.
• Rastrear todas as conversas junto com seus outros canais em uma única caixa de entrada.

Isso é ideal para empresas que usam ferramentas de comunicação especializadas, possuem uma plataforma personalizada ou desejam centralizar todas as mensagens dos clientes em um só lugar.

Como Funciona #

Os canais personalizados funcionam trocando mensagens entre sua plataforma externa e a plataforma usando webhooks (mensagens automatizadas enviadas entre sistemas pela internet). Aqui está o fluxo:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Mensagens recebidas: Sua plataforma externa envia mensagens para um endereço da web (URL). Pense nisso como sua plataforma “postando” uma mensagem na caixa de correio da plataforma.
2. Processamento: A plataforma cria ou atualiza o contato, armazena a mensagem e faz com que um Agente de IA gere uma resposta (se estiver ativo).
3. Mensagens enviadas: Quando a plataforma envia uma resposta (seja da IA ou digitada por você), ela envia a mensagem para uma URL na sua plataforma, onde seu sistema pode entregá-la ao usuário final.

Configurando Mensagens Recebidas (Sua Plataforma para o Aplicativo) #

Para enviar mensagens da sua plataforma externa para o aplicativo, sua plataforma precisa enviar dados para a seguinte URL. Seu desenvolvedor reconhecerá isso como uma solicitação POST padrão (uma maneira comum de um sistema enviar dados para outro pela internet).

Para onde enviar mensagens #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

Substitua YOUR_API_KEY pela sua chave de API (um código privado que prova à plataforma que sua plataforma tem permissão para enviar mensagens). Encontre ou gere-a em Configurações → Integrações → Chave de API.

Formato da mensagem #

Envie os dados da mensagem no seguinte formato (JSON):

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

O que cada parte significa:

• messageSid - Um ID exclusivo para esta mensagem específica (seu sistema cria isso). Usado para evitar que a mesma mensagem seja processada duas vezes.
• fromId - Quem enviou a mensagem (pode ser um ID de usuário, e-mail ou número de telefone do seu sistema).
• toId - Seu identificador de negócio (pode ser qualquer rótulo que você escolher).
• body - O texto real da mensagem.
• channel - Um rótulo que você escolhe para identificar de onde a mensagem veio (por exemplo, “website-chat”, “email”).

Referência Completa de Campos #

Reações com Emoji #

Se a sua plataforma suporta reações com emoji (um polegar para cima em uma mensagem, por exemplo), envie-as como uma reação em vez de uma mensagem de texto: defina messageType como "reaction" e coloque apenas o emoji em customData.body.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

O assistente então a trata da maneira que você esperaria:

• Uma reação a uma pergunta feita pelo assistente (por exemplo, “Quinta-feira funciona?”) é tratada como a resposta, e o assistente responde.
• Uma reação a uma mensagem de encerramento (por exemplo, “Até logo!”) encerra a conversa silenciosamente. Nenhuma resposta é enviada.

Se a sua plataforma transforma reações em texto, como “Reagiu com: 👍”, o assistente vê uma mensagem de texto normal e decide por conta própria se deve responder. Enviar o tipo de reação evita isso.

O que você recebe de volta #

Uma solicitação bem-sucedida retorna:

{
  "success": true,
  "messageId": "1234567890"
}

Se algo der errado, você receberá uma mensagem de erro explicando o problema:

{
  "error": "Message body cannot be empty"
}

Códigos de Status #

Se você definir customData.status, o único valor aceito é "received" — deixe-o de fora completamente para usar o padrão em vez de enviar qualquer outra coisa, ou você receberá um 400.

Enviando Anexos de Mídia (Imagens, Vídeos, Arquivos) #

Você pode incluir anexos de arquivo (imagens, vídeos, áudio, documentos) com suas mensagens. Existem duas maneiras de fazer isso:

Opção 1: Link para um arquivo #

Se o arquivo já estiver hospedado online, forneça a URL (endereço da web) onde a plataforma pode baixá-lo:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Opção 2: Incorporar o arquivo diretamente (Base64) #

Se o arquivo não estiver hospedado online, você pode incorporá-lo diretamente na mensagem como texto codificado (formato base64). Isso é comum em integrações técnicas onde seu sistema gera arquivos dinamicamente. A plataforma irá decodificar e armazenar o arquivo automaticamente:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Configurando Mensagens de Saída (da plataforma para a Sua Plataforma) #

Quando a plataforma envia uma resposta em um canal personalizado (seja da IA ou digitada por você), ela envia automaticamente essa resposta para uma URL na sua plataforma para que seu sistema possa entregá-la ao usuário final.

Defina a URL do webhook primeiro. Você deve salvar a URL do webhook do canal personalizado antes que qualquer resposta possa ser entregue. Se nenhuma URL for salva, as respostas ainda serão geradas e armazenadas, mas nunca serão enviadas — e elas não mostrarão um status de “Falha”, portanto, nada na sua caixa de entrada sinalizará o problema. Sempre configure a URL do webhook antes de entrar em operação.

Diga ao Aplicativo Para Onde Enviar as Respostas #

1. Na barra lateral esquerda, clique em Configurações perto da parte inferior.
2. Na barra lateral de Configurações, em Canais, clique em Canais.
3. Encontre o cartão Canal personalizado na parte inferior da página (após o Gateway de SMS Android, iMessage, o widget de chat do site, Conta Twilio e Conformidade regulatória).
4. Insira a URL do Webhook — a URL em sua plataforma para onde a IA deve enviar mensagens de saída (seu desenvolvedor configura isso para receber e processar respostas). Deve ser uma URL HTTPS pública — endereços http:// e hosts não públicos são rejeitados.
5. Clique em Salvar.

O que a Plataforma Envia para a Sua Plataforma #

Quando a plataforma envia uma resposta, sua plataforma receberá os seguintes dados:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}

O que Cada Campo Significa #

Sua plataforma recebe esses dados e os utiliza para entregar a resposta ao usuário final através do seu próprio sistema.

Como a Plataforma Rastreia a Entrega #

Após enviar a resposta para sua plataforma, a plataforma atualiza o status da mensagem:

• Enviado - Sua plataforma recebeu a mensagem com sucesso.
• Falha - Sua plataforma retornou um erro ou não pôde ser alcançada. A plataforma armazena os detalhes do erro com a mensagem para que você possa solucionar o problema.

Enviando mensagens do seu sistema para o aplicativo #

Além de receber mensagens, você também pode enviar mensagens de saída por meio de um canal personalizado diretamente do seu próprio sistema. Isso é útil quando você deseja iniciar uma conversa ou enviar uma mensagem proativa.

Requisito do plano. Enviar e sincronizar mensagens por meio da API requer um plano que inclua acesso à API e pelo menos um canal de mensagens. Se você receber um erro 403 “permission denied / feature not enabled”, seu plano atual não inclui isso — faça um upgrade do seu plano ou entre em contato com o suporte.

Onde enviar #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Formato da mensagem #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Campos obrigatórios #

Os campos opcionais (campaignId, firstName, lastName, email) funcionam da mesma forma que nas mensagens recebidas — eles ajudam a plataforma a criar ou atualizar o registro de contato.

O que você recebe de volta #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Registrando mensagens enviadas de outro sistema #

Às vezes, você já enviou uma mensagem para um contato de uma ferramenta diferente (por exemplo, um fluxo de trabalho em outra plataforma) e simplesmente deseja que a plataforma saiba disso para que a IA tenha o contexto completo. Isso é diferente de enviar: a plataforma registra a mensagem, mas não a reentrega ao contato.

Onde enviar #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

Inclua customData.fromId (o ID do contato na sua plataforma) e customData.body (o texto da mensagem que já foi enviada).

Como se comporta #

• A mensagem é registrada, não reenviada. A plataforma a armazena na conversa apenas para contexto.
• A IA é pausada nesse contato por padrão. Isso evita que o bot responda a uma mensagem que um humano já tratou. Para manter o bot ativo, passe customData.pauseAi: false.
• Novos contatos podem ser criados automaticamente. Inclua customData.customChannel e o contato será criado se ainda não existir.
• Duplicatas são ignoradas. Se você reutilizar o mesmo messageSid, a plataforma reconhece que a mensagem já foi registrada e não faz alterações.

Requisito do plano. Assim como o envio, a gravação de mensagens através da API requer um plano que inclua acesso à API e pelo menos um canal de mensagens. Um erro de 403 “permission denied / feature not enabled” significa que seu plano atual não inclui isso.

Exemplos do Mundo Real #

Chat ao Vivo no Site #

Conecte um widget de chat ao vivo em seu site à plataforma para que seu Agente de IA possa responder às perguntas dos visitantes:

1. Um visitante digita uma mensagem no widget de chat do seu site.
2. Seu widget de chat envia a mensagem para a plataforma.
3. O Agente de IA gera uma resposta.
4. A resposta é enviada de volta ao seu widget de chat, que a exibe para o visitante.

Por que isso é útil: Os visitantes do seu site obtêm respostas instantâneas e baseadas em IA para suas perguntas sem que você precise estar online.

E-mail #

Encaminhe conversas por e-mail através da plataforma para que seu Agente de IA possa responder a e-mails:

1. Configure um sistema que encaminhe e-mails recebidos para a plataforma (usando o endereço do remetente do e-mail como fromId, o assunto e o corpo do e-mail como body, e "email" como channel).
2. O Agente de IA lê o e-mail e gera uma resposta.
3. A resposta é enviada de volta ao seu sistema de e-mail, que a envia como uma resposta de e-mail normal.

Por que isso é útil: Perguntas comuns por e-mail (preços, horário de funcionamento, disponibilidade) são respondidas instantaneamente pelo seu Agente de IA.

Se o seu sistema de e-mail suporta IMAP/SMTP ou OAuth, o canal de E-mail integrado pode ser mais simples do que uma integração personalizada.

Integração com CRM #

Conecte seu sistema de CRM (gestão de relacionamento com o cliente) existente à plataforma:

1. Quando um lead envia uma mensagem através do seu CRM, encaminhe-a para a plataforma.
2. O Agente de IA responde e rastreia a conversa.
3. A resposta da IA é enviada de volta ao seu CRM para entrega.
4. O histórico completo da conversa fica disponível tanto na plataforma quanto no seu CRM.

Por que isso é útil: Sua equipe de vendas obtém respostas assistidas por IA para leads sem sair do CRM.

Sistema de Tickets de Suporte #

Use a plataforma como um primeiro atendimento baseado em IA para suporte ao cliente:

1. Seu sistema de tickets encaminha novos tickets de suporte para a plataforma.
2. O Agente de IA envia uma resposta inicial (por exemplo, confirmando o recebimento do ticket e fazendo perguntas de esclarecimento).
3. A resposta é anexada ao ticket no seu sistema de suporte.
4. Sua equipe de suporte pode revisar o que a IA disse e assumir o atendimento quando necessário.

Por que isso é útil: Os clientes recebem uma confirmação imediata e ajuda inicial, mesmo fora do horário comercial.

Solução de problemas #

Mensagens não sendo recebidas pela plataforma #

• Verifique se sua chave de API está correta e ativa (verifique Configurações → Integrações → Chave de API).
• Certifique-se de que você está enviando uma solicitação POST (não GET). Seu desenvolvedor saberá a diferença.
• Verifique se o campo customData.body não está vazio ou contendo apenas espaços em branco.
• Verifique se o campo customData.fromId está incluído.
• Leia a mensagem de resposta para obter detalhes específicos do erro.

Respostas não chegando à sua plataforma #

• Certifique-se de ter inserido a URL da sua plataforma no cartão Canal personalizado na página Canais. Se nenhuma URL for salva, as respostas são geradas e armazenadas, mas nunca enviadas — e elas não serão marcadas como “Falha”, então verifique isso primeiro.
• Verifique se a URL é acessível publicamente (não está atrás de um login ou firewall) e retorna uma resposta de sucesso.
• Apenas respostas (mensagens de saída) são enviadas para sua URL — mensagens recebidas não acionam isso.
• Verifique os detalhes do erro na mensagem em sua caixa de entrada.

Contato não sendo criado #

• Certifique-se de que o valor fromId seja consistente para o mesmo usuário em todas as suas mensagens. A plataforma usa esse valor para identificar contatos — se ele mudar entre as mensagens, a plataforma criará um novo contato a cada vez.
• Inclua firstName, lastName e email na primeira mensagem de um novo contato para criar um registro de contato completo.

Anexos de mídia não funcionando #

• Para links de arquivos (URLs), certifique-se de que o arquivo seja publicamente acessível (nenhum login é necessário para acessá-lo).
• Sempre inclua mediaContentType quando incluir mediaUrl.
• Para arquivos incorporados (base64), verifique se o formato é data:MIME_TYPE;base64,ENCODED_DATA.
• Certifique-se de que o tipo de arquivo que você especifica corresponda ao conteúdo real do arquivo.

Melhores práticas #

• Use valores fromId consistentes. Cada usuário na sua plataforma deve sempre ter o mesmo fromId. Isso garante que a plataforma agrupe todas as suas mensagens em uma única conversa, em vez de criar contatos duplicados.
• Escolha um nome channel claro. Escolha algo descritivo como "website-chat", "email" ou "zendesk" para que você possa identificar facilmente de onde as mensagens vieram ao visualizar sua caixa de entrada.
• Inclua detalhes de contato (firstName, lastName, email) na primeira mensagem de um novo contato. Isso cria um registro de contato completo e útil imediatamente.
• Implemente lógica de nova tentativa. Faça com que sua plataforma tente reenviar mensagens caso a plataforma não responda na primeira tentativa (problemas de rede acontecem).
• Use valores messageSid exclusivos para cada mensagem. Isso evita que a mesma mensagem seja processada duas vezes se o seu sistema a enviar mais de uma vez.
• Use campaignId para rotear mensagens para diferentes Agentes de IA quando você tiver vários casos de uso (por exemplo, consultas de vendas vs. perguntas de suporte).
• Teste antes de entrar em operação. Envie mensagens de teste em ambas as direções e verifique se os contatos, conversas e respostas da IA funcionam corretamente antes de lançar para usuários reais.