# 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](whatsapp-business.md), [SMS](sms.md), [Instagram](instagram-dms.md), [Messenger](facebook-messenger.md)). 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. ::: note **Nota:** Os canais personalizados requerem alguma configuração técnica. Se você ou a sua equipa não se sentirem à vontade com integrações técnicas, poderá querer pedir ajuda ao seu programador web ou à equipa de TI para esta secção. ::: --- ## 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): ```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 | Campo | Obrigatório? | O que faz | |---|---|---| | `customData.messageSid` ou `customData.id` | Sim | Um ID único para esta mensagem (evita duplicados) | | `customData.fromId` | Sim | Identifica quem enviou a mensagem (por exemplo, um ID de utilizador, e-mail ou número de telefone do seu sistema) | | `customData.toId` | Sim | Identifica o lado recetor (a sua empresa). Pode ser qualquer texto à sua escolha. | | `customData.body` | Sim | O texto real da mensagem. Não pode estar vazio. | | `customData.status` | Não | Estado da mensagem. Deixe em branco para usar o padrão (`"received"`). | | `customData.channel` | Não | Uma etiqueta para a origem (por exemplo, `"live-chat"`, `"email"`, `"my-crm"`). Ajuda-o a identificar de onde vieram as mensagens na sua caixa de entrada. | | `customData.campaignId` | Não | Um ID de campanha/Agente. Use isto para encaminhar a mensagem para uma configuração de IA específica. | | `customData.firstName` | Não | Nome próprio do contacto. Incluído ao criar um novo registo de contacto. | | `customData.lastName` | Não | Apelido do contacto. Incluído ao criar um novo registo de contacto. | | `customData.email` | Não | Endereço de e-mail do contacto. Incluído ao criar um novo registo de contacto. | | `customData.mediaUrl` | Não | Uma ligação para um ficheiro anexo (imagem, vídeo, áudio ou documento). Também pode ser um ficheiro codificado em base64 (ver abaixo). | | `customData.mediaContentType` | Não | O tipo de ficheiro (por exemplo, `"image/jpeg"`, `"video/mp4"`, `"audio/ogg"`, `"application/pdf"`). Obrigatório se incluir `mediaUrl`. | | `messageType` | Não | Tipo de mensagem. Deixe em branco para texto normal. Defina como `"reaction"` para reações com emoji. | ### 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`. ```json { "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: ```json { "success": true, "messageId": "1234567890" } ``` Se algo correr mal, receberá uma mensagem de erro a explicar o problema: ```json { "error": "Message body cannot be empty" } ``` ### Códigos de Estado | Código | O que significa | |---|---| | `200` | Sucesso - mensagem recebida e a ser processada | | `400` | Algo está errado com o seu pedido - verifique se faltam campos obrigatórios ou se o corpo da mensagem está vazio | | `401` | Chave de API inválida - verifique a chave em **Definições → Integrações → Chave de API** | | `405` | Método de pedido incorreto - certifique-se de que está a utilizar POST, não GET | | `500` | Algo correu mal do lado da plataforma - tente novamente dentro de alguns momentos | > 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: ```json { "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: ```json { "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" } ``` ::: note **Nota:** Incorporar ficheiros diretamente torna os dados da mensagem muito maiores. Para ficheiros grandes, é preferível alojar o ficheiro online e enviar uma ligação (Opção 1) em vez disso. ::: --- ## 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: ```json { "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 | Campo | O que contém | |---|---| | `contactId` | o ID interno da plataforma para este contacto | | `messageId` | O ID único desta mensagem na aplicação | | `userId` | O seu ID de utilizador | | `body` | O texto da resposta | | `toId` | O ID do contacto na sua plataforma (corresponde ao `fromId` que enviou na mensagem de entrada) | | `channel` | A etiqueta do canal personalizado que atribuiu | 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 ```json { "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 | Campo | O que faz | |---|---| | `customData.fromId` | O ID do contacto na sua plataforma | | `customData.customChannel` | O nome do seu canal personalizado (por exemplo, "my-live-chat") | | `customData.body` | O texto da mensagem a enviar | 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 ```json { "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](email.md) 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.