Início Rápido do Canal Personalizado

Esta integração permite que a sua equipa converse com os seus clientes através de qualquer canal de mensagens através de uma implementação personalizada.

Ligar um canal personalizado

Passo 1: Vá para Definições > Canais

Passo 2: Clique em Adicionar canal > Canal personalizado > Ligar

Passo 3: Introduza o URL do Webhook de destino para onde as mensagens de saída serão enviadas.

Passo 4: Selecione o tipo de ID para o canal > clique em Seguinte

Os tipos de ID são utilizados para a identificação do utilizador e para a comunicação com o seu servidor de integração personalizado.

Existem dois tipos de IDs disponíveis:

1. Número de telefone: utilize isto se o fornecedor de serviços de mensagens reconhecer contactos com base no número de telefone.

   1. Formato de amostra: +60177872890

2. ID personalizado: utilize isto se o fornecedor de serviços de mensagens reconhecer os contactos com base num ID gerado personalizado.

   1. O comprimento máximo dos caracteres é de 50.

   2. A-Z, a-z, 0-9, _ , =, + , / e @ são permitidos.

Passo 5: A caixa de diálogo a seguir fornecerá o ID do canal, o Token da API e a URL do Webhook, por exemplo.

1. ID do canal: gfd8g7fd89dgfd

2. Token da API: aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd

3. URL do Webhook: https://webhook.respond.io/custom/channel/webhook/

   A utilização de um tipo de ID de número de telefone permite iniciar uma conversa e enviar a primeira mensagem para um contacto.

Passar mensagens para respond.io

URL do Webhook é usada para publicar as Mensagens, Ecos de Mensagens e Recibos de Mensagens na plataforma respond.io.

O código fornecido irá desencadear o webhook no respond.io, criando um contacto, se necessário, e guardando a mensagem nesse contacto.

Exemplo de mensagens

curl -X POST \\  
  https://app.respond.io/custom/channel/webhook/ \\  
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \\  
  -H 'cache-control: no-cache' \\  
  -H 'content-type: application/json' \\  
  -d '{  
  "channelId": "gfd8g7fd89dgfd",  
  "contactId": "+60177872890",  
  "events": \[  
    {  
      "type": "message",  
      "mId": "xcvzzxcxczxczxc",  
      "timestamp": 2132131321000,  
      "message": {  
        "type": "text",  
        "text": "Hello World"  
      }  
    }  
  \],  
  "contact": {  
    "firstName": "John",  
    "lastName": "Doe",  
    "profilePic": "<https://static.independent.co.uk/s3fs-public/thumbnails/image/2015/07/08/14/pic.jpg>",  
    "countryCode": "MY",  
    "email": "john@respond.io",  
    "phone": "+60177872890",  
    "language": "en"  
  }  
}'},{

Amostra para ecos de mensagens

curl -X POST \\  
  https://webhook.respond.io/custom/channel/webhook/ \\  
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \\  
  -H 'cache-control: no-cache' \\  
  -H 'content-type: application/json' \\  
  -d '{  
  "channelId": "gfd8g7fd89dgfd",  
  "contactId": "+60177872890",  
  "events": \[  
    {  
      "type": "message_echo",  
      "mId": "xcvzzxcxczxczxc",  
      "timestamp": 2132131321000,  
      "message": {  
        "type": "text",  
        "text": "Hello World"  
      }  
    }  
  \],  
  "contact": {  
    "firstName": "John",  
    "lastName": "Doe",  
    "profilePic": "<https://static.independent.co.uk/s3fs-public/thumbnails/image/2015/07/08/14/pic.jpg>",  
    "countryCode": "MY",  
    "email": "john@respond.io",  
    "phone": "+60177872890",  
    "language": "en"  
  }  
}'}]}]

Exemplo de recibos de mensagens

curl -X POST \\  
  https://webhook.respond.io/custom/channel/webhook/ \\  
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \\  
  -H 'cache-control: no-cache' \\  
  -H 'content-type: application/json' \\  
  -d '{  
  "channelId": "gfd8g7fd89dgfd",  
  "contactId": "+60177872890",  
  "events": \[  
    {  
      "type": "message\_status",  
      "mId": "xcvzzxcxczxczxc",  
      "timestamp": 2132131321000,  
      "status": {  
        "value": "sent|delivered|read|failed",  
        "message": "Error: Sending failed due to invalid token"  
      }  
    }  
  \],  
}'}]}<|future|>Assistant

Resposta - Sucesso (estado HTTP → 200)

"OK"

Gerir mensagens de saída do respond.io

respond.io irá chamar o endpoint <API Base URL>/message

Certifique-se de aplicar o código Mensagem de saída na rota /message do seu servidor web.

Eis o exemplo cURL de respond.io a chamar o endpoint:

curl -X POST \\  
  <API Base URL>/message \\  
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \\  
  -H 'cache-control: no-cache' \\  
  -H 'content-type: application/json' \\  
  -d '{  
	"channelId": "gfd8g7fd89dgfd",  
	"contactId": "+60177872890",  
	"message": {  
		"type": "text",  
		"text": "Hello World"  
	}  
}'

Resposta - Sucesso (estado HTTP → 200)

{  
	"mId": "1640141607842"  
}

A autenticação necessita de ocorrer no ponto final antes de enviar a mensagem para o fornecedor de serviços de mensagens.

Aqui está um exemplo de uso de um middleware express para esse propósito:

const {validationResult} = require('express-validator');

const validateToken = (req, res, next) => {
    const apiToken = <>;
    const bearerToken = req.headers.authorization;

    if (!bearerToken) {
        return res.send(401);
    }

    const token = bearerToken.substring(7, bearerToken.length);

    if (apiToken !== token) {
        return res.send(401);
    }
    next();
};

module.exports = {
    validateToken
};

Incluímos um exemplo de um Canal Personalizado que você pode testar no seu servidor. Confira nosso projeto no GitHub aqui.

Tipo de mensagens

Exemplo de texto

{  
  "tipo": "texto",  
  "texto": "Bem-vindo ao respond.io",  
}

Amostra para arquivo de média

{  
  "type": "attachment",  
  "attachment": {  
    "type": "image|video|audio|file",  
    "url": "https://abc/japan.png",  
    "mimeType": "image/png",  
    "fileName":"company logo.png",  
    "description": "latest company logo"  
  }  
}

Certifique-se de que a URL do anexo não seja baixada forçadamente pelo navegador. O cabeçalho de resposta HTTP's Content-Disposition deve ter o valor por defeito, que é inline.

Amostra para localização

{  
  "tipo": "localização",  
  "latitude": 0,123456,  
  "longitude": -0.1234,  
  "endereço": "Sky Suites, Jalan P. Ramlee, Kuala Lumpur, 50250 Kuala Lumpur, Wilayah Persekutuan Kuala Lumpur"  
}

Exemplo de resposta rápida

{  
  "tipo": "resposta rápida",  
  "título": "Selecione o seu idioma preferido",    
  "respostas": \[  
    "Malaio",  
    "Inglês"  
  \]  
}

Códigos de erro

Erro (Estado HTTP → 4xx)

Configuração de canal

Passo 1: Clique em Definições > Canais

Passo 2: Localizar Canal Personalizado > clicar em Gerir

Passo 3: Na página Configuração de canal personalizado verá as seguintes definições:

• Ícone do canal - Carregue uma imagem que sirva de ícone para o seu canal personalizado.

• Nome do canal - O nome do canal pode ser alterado e é utilizado internamente para identificar o canal.

• URL do webhook para mensagens de saída — O URL do webhook para mensagens de saída para este canal.

• URL do webhook para mensagens recebidas — O URL do webhook para mensagens recebidas neste canal.

• Tipo de ID — São utilizados para a identificação do utilizador e para comunicar com o seu servidor de integração personalizado.

• ID do canal — ID de canal exclusivo para identificar o seu canal personalizado.

• API Token — Um identificador único utilizado para autenticar um utilizador para aceder a uma API.

Passo 4: Clique em Guardar alterações para atualizar a configuração do canal personalizado.

Perguntas Frequentes e Resolução de Problemas

Posso conectar chats de outras plataformas usando um Canal Personalizado?

Sim, você pode. Aqui estão três passos a seguir:

1. No respond.io, insira a URL do webhook de destino da outra plataforma no campo URL do Webhook para Mensagem de Entrada.

2. Na outra plataforma, configure uma URL do webhook apontando para o respond.io, permitindo que os Contatos enviem mensagens de volta para você.

3. Você precisará de um Servidor de Integração Personalizada para interpretar APIs tanto do respond.io quanto da outra plataforma, permitindo a troca de mensagens entre eles.

Certifique-se de confirmar com a outra plataforma que os dois primeiros passos são viáveis.

Perguntas Frequentes sobre Webhooks de Canal Personalizado

Por que o webhook retorna um status 200 mesmo que a mensagem falhe ao ser entregue ao respond.io?

Ao conectar um Canal Personalizado, as mensagens enviadas para o respond.io através de webhooks sempre retornarão um código de status 200 imediatamente, independentemente de a mensagem ter sido passada com sucesso para o respond.io. Isso se deve à natureza dos webhooks, que são projetados para retornar uma resposta imediata sem verificar o sucesso da entrega da mensagem.