Canais Personalizados #

Ligue qualquer plataforma de mensagens ou ferramenta de comunicação à plataforma utilizando canais personalizados. Isto permite-lhe trazer mensagens de plataformas como widgets de chat ao vivo em websites, sistemas de e-mail, CRMs ou qualquer outro serviço para a sua caixa de entrada — e responder-lhes com o seu Agente de IA.

O que são Canais Personalizados? #

Os canais personalizados expandem a plataforma para além das suas plataformas de mensagens integradas (WhatsApp, SMS, Instagram, Messenger). Com canais personalizados, pode:

• Receber mensagens de qualquer plataforma externa na caixa de entrada unificada da plataforma.
• Enviar respostas da aplicação de volta para a sua plataforma externa automaticamente.
• Utilizar um Agente de IA para responder a mensagens de qualquer origem.
• Acompanhar todas as conversas juntamente com os seus outros canais numa única caixa de entrada.

Isto é ideal para empresas que utilizam ferramentas de comunicação especializadas, possuem uma plataforma personalizada ou pretendem reunir todas as mensagens dos clientes num só local.

Como Funciona #

Os canais personalizados funcionam através da troca de mensagens entre a sua plataforma externa e a plataforma utilizando webhooks (mensagens automatizadas enviadas entre sistemas através da internet). Eis 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: A sua plataforma externa envia mensagens para um endereço web (URL). Pense nisto como a sua plataforma a “publicar” uma mensagem na caixa de correio da plataforma.
2. Processamento: A plataforma cria ou atualiza o contacto, 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 escrita por si), envia a mensagem para um URL na sua plataforma, onde o seu sistema a pode entregar ao utilizador final.

Configurar Mensagens Recebidas (Da sua Plataforma para a Aplicação) #

Para enviar mensagens da sua plataforma externa para a aplicação, a sua plataforma precisa de enviar dados para o seguinte URL. O seu programador reconhecerá isto como um pedido POST padrão (uma forma comum de um sistema enviar dados para outro através da 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 a sua plataforma tem permissão para lhe enviar mensagens). Encontre-a ou gere-a em Definiçõ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 único para esta mensagem específica (o seu sistema cria este ID). Utilizado para evitar que a mesma mensagem seja processada duas vezes.
• fromId - Quem enviou a mensagem (pode ser um ID de utilizador, e-mail ou número de telefone do seu sistema).
• toId - O identificador da sua empresa (pode ser qualquer etiqueta que escolha).
• body - O texto da mensagem propriamente dito.
• channel - Uma etiqueta que escolhe para identificar a origem da mensagem (por exemplo, “website-chat”, “email”).

Referência Completa dos Campos #

Reações com Emoji #

Se a sua plataforma suporta reações com emoji (um polegar para cima numa 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 trata-as então da forma que seria de esperar:

• Uma reação a uma pergunta feita pelo assistente (por exemplo, “A quinta-feira dá jeito?”) é tratada como a resposta, e o assistente responde.
• Uma reação a uma mensagem de despedida (por exemplo, “Falamos em breve!”) termina a conversa silenciosamente. Não é enviada qualquer resposta.

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

O que recebe de volta #

Um pedido bem-sucedido devolve:

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

Se algo correr mal, receberá uma mensagem de erro a explicar o problema:

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

Códigos de Estado #

Se definir customData.status, o único valor aceite é "received" — omita-o completamente para utilizar o valor predefinido em vez de enviar qualquer outra coisa, ou receberá um 400.

Envio de Anexos de Multimédia (Imagens, Vídeos, Ficheiros) #

Pode incluir ficheiros em anexo (imagens, vídeos, áudio, documentos) nas suas mensagens. Existem duas formas de o fazer:

Opção 1: Ligação para um Ficheiro #

Se o ficheiro já estiver alojado online, forneça o URL (endereço web) onde a plataforma o pode descarregar:

{
  "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 Ficheiro Diretamente (Base64) #

Se o ficheiro não estiver alojado online, pode incorporá-lo diretamente na mensagem como texto codificado (formato base64). Isto é comum em integrações técnicas onde o seu sistema gera ficheiros em tempo real. A plataforma irá descodificar e armazenar o ficheiro 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"
}

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

Quando a plataforma envia uma resposta num canal personalizado (seja da IA ou escrita por si), envia automaticamente essa resposta para um URL na sua plataforma para que o seu sistema a possa entregar ao utilizador final.

Defina primeiro o URL do webhook. Deve guardar o URL do webhook do canal personalizado antes que quaisquer respostas possam ser entregues. Se não for guardado nenhum URL, as respostas continuam a ser geradas e armazenadas, mas nunca são enviadas — e não mostrarão um estado de “Falha”, pelo que nada na sua caixa de entrada sinalizará o problema. Configure sempre o URL do webhook antes de entrar em funcionamento.

Indique à Aplicação para onde enviar as Respostas #

1. Na barra lateral esquerda, clique em Definições perto da parte inferior.
2. Na barra lateral de Definiçõ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 website, Conta Twilio e Conformidade regulamentar).
4. Introduza o URL do Webhook — o URL na sua plataforma para onde a IA deve enviar as mensagens de saída (o seu programador configura isto para receber e processar respostas). Tem de ser um URL HTTPS público — endereços http:// e anfitriões não públicos são rejeitados.
5. Clique em Guardar.

O que a plataforma envia para a Sua Plataforma #

Quando a plataforma envia uma resposta, a 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 significa cada campo #

A sua plataforma recebe estes dados e utiliza-os para entregar a resposta ao utilizador final através do seu próprio sistema.

Como a plataforma monitoriza a entrega #

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

• Enviada - A sua plataforma recebeu a mensagem com sucesso.
• Falhou - A sua plataforma devolveu um erro ou não pôde ser contactada. A plataforma armazena os detalhes do erro com a mensagem para que possa diagnosticar o problema.

Enviar mensagens do seu sistema para a aplicação #

Para além de receber mensagens, também pode enviar mensagens de saída através de um canal personalizado diretamente a partir do seu próprio sistema. Isto é útil quando pretende iniciar uma conversa ou enviar uma mensagem proativa.

Requisito do plano. O envio e a sincronização de mensagens através da API requerem um plano que inclua acesso à API e, pelo menos, um canal de mensagens. Se receber um erro 403 “permission denied / feature not enabled”, o seu plano atual não inclui esta funcionalidade — faça o upgrade do seu plano ou contacte 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 — ajudam a plataforma a criar ou atualizar o registo do contacto.

O que recebe de volta #

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

Registar mensagens enviadas a partir de outro sistema #

Por vezes, já enviou uma mensagem a um contacto a partir de uma ferramenta diferente (por exemplo, um fluxo de trabalho noutra plataforma) e pretende simplesmente que a plataforma saiba disso para que a IA tenha o contexto completo. Isto é diferente de enviar: a plataforma regista a mensagem mas não a reentrega ao contacto.

Onde enviar #

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

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

Como se comporta #

• A mensagem é registada, não reenviada. A plataforma armazena-a na conversa apenas para contexto.
• A IA é pausada nesse contacto por predefinição. Isto evita que o bot responda por cima de uma mensagem que um humano já tratou. Para manter o bot ativo, passe customData.pauseAi: false.
• Podem ser criados novos contactos automaticamente. Inclua customData.customChannel e o contacto será criado se ainda não existir.
• Os duplicados são ignorados. Se reutilizar o mesmo messageSid, a plataforma reconhece que a mensagem já foi registada e não faz alterações.

Requisito do plano. Tal 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 403 “permission denied / feature not enabled” significa que o seu plano atual não inclui esta funcionalidade.

Exemplos do Mundo Real #

Chat em Direto no Website #

Ligue um widget de chat ao vivo no seu website à plataforma para que o seu Agente de IA possa responder às perguntas dos visitantes:

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

Por que é útil: Os visitantes do seu website obtêm respostas instantâneas e baseadas em IA às suas perguntas sem que precise de estar online.

E-mail #

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

1. Configure um sistema que reencaminhe os e-mails recebidos para a plataforma (utilizando 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 para o seu sistema de e-mail, que a envia como uma resposta de e-mail normal.

Por que isto é útil: Perguntas comuns por e-mail (preços, horários, 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 #

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

1. Quando um potencial cliente envia uma mensagem através do seu CRM, reencaminhe-a para a plataforma.
2. O Agente de IA responde e acompanha a conversa.
3. A resposta da IA é enviada de volta para o seu CRM para entrega.
4. O histórico completo da conversa está disponível tanto na plataforma como no seu CRM.

Por que é útil: A sua equipa de vendas obtém respostas assistidas por IA para potenciais clientes sem sair do seu CRM.

Sistema de Pedidos de Suporte #

Utilize a plataforma como um primeiro interveniente com IA para apoio ao cliente:

1. O seu sistema de gestão de pedidos de suporte reencaminha novos pedidos para a plataforma.
2. O Agente de IA envia uma resposta inicial (por exemplo, confirmando a receção do pedido e colocando questões de esclarecimento).
3. A resposta é anexada ao pedido no seu sistema de suporte.
4. A sua equipa de suporte pode rever o que a IA disse e assumir o controlo quando necessário.

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

Resolução de Problemas #

Mensagens Não Recebidas pela plataforma #

• Verifique se a sua chave de API está correta e ativa (verifique Definições → Integrações → Chave de API).
• Certifique-se de que está a enviar um pedido POST (não GET). O seu programador saberá a diferença.
• Verifique se o campo customData.body não está vazio ou contém apenas espaços em branco.
• Verifique se o campo customData.fromId está incluído.
• Leia a mensagem de resposta para obter detalhes específicos sobre o erro.

Respostas Não Chegam à Sua Plataforma #

• Certifique-se de que introduziu o URL da sua plataforma no cartão Canal personalizado na página Canais. Se não for guardado nenhum URL, as respostas são geradas e armazenadas, mas nunca enviadas — e não serão marcadas como “Falhadas”, por isso verifique isto primeiro.
• Verifique se o URL é publicamente acessível (não está atrás de um início de sessão ou firewall) e devolve uma resposta de sucesso.
• Apenas as respostas (mensagens de saída) são enviadas para o seu URL — as mensagens recebidas não acionam este processo.
• Verifique os detalhes do erro na mensagem na sua caixa de entrada.

Contacto Não Criado #

• Certifique-se de que o valor fromId é consistente para o mesmo utilizador em todas as suas mensagens. A plataforma utiliza este valor para identificar contactos — se este mudar entre mensagens, a plataforma criará um novo contacto de cada vez.
• Inclua firstName, lastName e email na primeira mensagem de um novo contacto para criar um registo de contacto completo.

Anexos de Multimédia Não Funcionam #

• Para links de ficheiros (URLs), certifique-se de que o ficheiro é publicamente acessível (não é necessário iniciar sessão para aceder ao mesmo).
• Inclua sempre mediaContentType quando incluir mediaUrl.
• Para ficheiros incorporados (base64), verifique se o formato é data:MIME_TYPE;base64,ENCODED_DATA.
• Certifique-se de que o tipo de ficheiro que especifica corresponde ao conteúdo real do ficheiro.

Melhores práticas #

• Utilize valores fromId consistentes. Cada utilizador na sua plataforma deve ter sempre o mesmo fromId. Isto garante que a plataforma agrupa todas as suas mensagens numa única conversa em vez de criar contactos duplicados.
• Escolha um nome channel claro. Escolha algo descritivo como "website-chat", "email" ou "zendesk" para que possa identificar facilmente de onde vieram as mensagens ao visualizar a sua caixa de entrada.
• Inclua detalhes de contacto (firstName, lastName, email) na primeira mensagem de um novo contacto. Isto cria um registo de contacto completo e útil de imediato.
• Implemente lógica de repetição. Faça com que a sua plataforma tente reenviar mensagens se a plataforma não responder na primeira tentativa (falhas de rede acontecem).
• Utilize valores messageSid únicos para cada mensagem. Isto evita que a mesma mensagem seja processada duas vezes se o seu sistema a enviar mais do que uma vez.
• Utilize campaignId para encaminhar mensagens para diferentes Agentes de IA quando tiver múltiplos casos de utilização (por exemplo, pedidos de vendas vs. questões de suporte).
• Teste antes de entrar em funcionamento. Envie mensagens de teste em ambas as direções e verifique se os contactos, conversas e respostas da IA funcionam corretamente antes de lançar para utilizadores reais.