Tabla de contenido
Canal personalizado
Cómo funciona
Recibiendo un mensaje
Para recibir un mensaje a través de un canal personalizado, es necesario seguir los siguientes pasos:
- Cuando un contacto intenta enviar un mensaje, el proveedor de servicios de mensajería llamará a su servidor de integración personalizado con el payload del mensaje (por favor revise la documentación API del proveedor de servicios de mensajería para referencia).
- Su servidor de integración personalizada recibirá el mensaje y lo publicará en respond.io (en formato respond.io).
- respond.io recibirá la solicitud de publicación, guardará el mensaje y lo mostrará en el módulo de mensajería.
Enviando un mensaje
Para enviar un mensaje a través de un canal personalizado, es necesario seguir los siguientes pasos:
- Cuando un User/Workflow/Broadcast intentará enviar un mensaje, respond.io llamará a su servidor de integración personalizado con la carga del mensaje (en formato respond.io).
- Su servidor de integración personalizada recibirá el mensaje y lo enviará al proveedor de servicios de mensajería en el formato que necesiten (por favor, revise la documentación de la API del proveedor de servicios de mensajería para referencia).
- El proveedor de servicios de mensajería recibirá el Webhook y confirmará si el mensaje ha sido entregado con éxito. Sugerencia, si el mensaje no se entrega con éxito puede intentar añadir un mecanismo de reintento en su servidor de integración personalizado.
Configuración
Paso 1: Crear un canal
- En la plataforma respond.io, vaya a Ajustes > Canales y haga clic en el botón AÑADIR CHANNEL
- Selecciona Canal Personalizado.
- Introduzca la URL base de la API.
- Seleccione el tipo de ID para el canal y haga clic en SIGUIENTE. Este ID es para el propósito de la identificación de usuario y se utilizará para comunicarse con su servidor de integración personalizado. Hay dos tipos de ID disponibles:
- Número de teléfono: Utilice esto si el proveedor de servicios de mensajería reconoce contactos basados en su número de teléfono.
- Formato de muestreo:
+60177872890
- Formato de muestreo:
- ID personalizado: Utilice esto si el proveedor del servicio de mensajería reconoce contactos basados en un ID generado a medida.
- La longitud máxima del caracter es 50.
A-Z,a-z,0-9,_,=,+,/y@están permitidos.
- Número de teléfono: Utilice esto si el proveedor de servicios de mensajería reconoce contactos basados en su número de teléfono.
- El siguiente cuadro de diálogo proporcionará el ID del canal, token de APIy URL del webhook p.e.
- ID del canal:
gfd8g7fd89dgfd - API Token:
aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd - URL de webhook:
https://app.respond.io/custom/channel/webhook/
- ID del canal:
Paso 2: Pasar mensajes a respond.io
Webhook URL se utiliza para POST de los Mensajes, Echoes de Mensajería y recibos de Mensajería para la respuesta. o plataforma.
El siguiente código llamará al webhook en la respuesta. o plataforma y estará creando el contacto (si no existe) y guardando el mensaje contra el contacto.
Ejemplo de mensajes
curl -X POST \
https://app.respond. o/custom/channel/webhook/ \
-H 'autorización: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"channelId": "gfd8g7fd89dgfd",
"contactId": "+60177872890",
"eventos": [
{
"tipo": "mensaje",
"mId": "xcvzzxcxczxczxc",
"marca de tiempo": 2132131321000,
"mensaje": {
"type": "texto",
"texto": "Hola Mundo"
}
}
],
"contacto": {
"firstName": "Juan",
"apellido": "Doe",
"profilePic": "<https://static.independent.co.uk/s3fs-public/thumbnails/image/2015/07/08/14/pic.jpg>",
"countryCode": "MY",
"email": "john@respond. o",
"teléfono": "+60177872890",
"idioma": "es"
}
}'
Ejemplo de Echoes de Mensajes
curl -X POST \
https://app.respond. o/custom/channel/webhook/ \
-H 'autorización: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"channelId": "gfd8g7fd89dgfd",
"contactId": "+60177872890",
"eventos": [
{
"tipo": "message_echo",
"mId": "xcvzzxcxczxczxc",
"marca de tiempo": 2132131321000,
"mensaje": {
"type": "texto",
"texto": "Hola Mundo"
}
}
],
"contacto": {
"firstName": "Juan",
"apellido": "Doe",
"profilePic": "<https://static.independent.co.uk/s3fs-public/thumbnails/image/2015/07/08/14/pic.jpg>",
"countryCode": "MY",
"email": "john@respond. o",
"teléfono": "+60177872890",
"idioma": "es"
}
}'
Ejemplo de recibos de mensajería
curl -X POST \
https://app.respond. o/custom/channel/webhook/ \
-H 'autorización: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"channelId": "gfd8g7fd89dgfd",
"contactId": "+60177872890",
"eventos": [
{
"tipo": "message_status",
"mId": "xcvzzxcxczxczxc",
"marca de tiempo": 2132131321000,
"status": {
"value": "sent|delivered|read|failed",
"mensaje": "Error: Error al enviar el token no válido"
}
]
}'
Campo | Descripción | Validación |
Id del canal | ID de Canal Único | Requerido. Campo único. Se genera por respond.io. |
contactId | ID de contacto único | Requerido. Id de contacto único respond.io. Máx. 50 caracteres. |
events.type | Tipo de evento | Requerido. Tipo disponible: mensaje, message_echo, y message_status. |
events.mld | ID del mensaje | Requerido. Mensaje único ID. Máx. 50 caracteres. |
events.timestamp | Tiempo de Epoch de UNIX (milisegundos) | Requerido. Tiempo del evento que activó el callback. |
events.message.type | Tipo de mensaje | Requerido. Tipos de mensajes disponibles: texto, adjunto, ubicación y quick_reply. Consulte la sección Tipo de mensaje para ver otras muestras de tipo de mensaje. |
texto de events.message.text | Texto del mensaje | Requerido. Longitud máxima de 7,000 caracteres. |
events.status.value | Texto | Requerido si event.type es message_status. Valores de estado disponibles: enviados, entregados, leídos y fallidos. |
events.status.message | Texto | Requerido si events.status.value es fallado. |
contacto.firstName | Nombre | Opcional. Máx. 50 caracteres. |
contacto.apellido | Apellido | Opcional. Máx. 50 caracteres. |
contacto.profilePic | URL de foto de perfil | Opcional. El tamaño del avatar no debe ser superior a 100 kb. Recomendado 720x720. |
contacto.locale | Código local | Opcional. Consulte aquí la lista de valores. |
contacto.countryCode | Código del país | Opcional. Código del país de 2 letras - Código ISO ALPHA-2. |
contacto.zona horaria | Zona horaria | Opcional. (min: -24) (max: 24). |
contacto.email | Correo Electrónico | Opcional. Máx. 50 caracteres. |
contacto.teléfono | Número de teléfono | Opcional. Máx. 18 caracteres. |
contacto.language | Idioma | Opcional. ISO 639-1. |
Respuesta - Éxito (estado HTTP → 200)
"OK"
Paso 3: Manejar mensajes salientes de respond.io
respond.io llamará al siguiente endpoint <API Base URL>/message
/message en tu servidor web.Aquí está el ejemplo de cURL de respond.io llamando al punto final.
curl -X POST \
<API Base URL>/message \
-H 'autorización: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"channelId": "gfd8g7fd89dgfd",
"contactId": "+60177872890",
"mensaje": {
"tipo": "texto",
"texto": "Hola Mundo"
}
}'
Respuesta - Éxito (estado HTTP → 200)
{
"mId": "1640141607842"
}La autenticación tiene que hacerse en el punto final antes de pasar el mensaje al proveedor del servicio de mensajería. Aquí está un ejemplo expreso de middleware.
const {validationResult} = require('express-validator');
const validateToken = (req, res, next) => {
const apiToken = <<API Token>>
const bearerToken = req. eaders.authorization;
if (!bearerToken)
return res. end(401)
const token = bearerToken.substring(7, bearerToken. ength);
if (apiToken !== token) {
return res. end(401)
}
siguiente();
};
módulo. xports = {
validateToken
};Tipo de mensajes
Ejemplo de texto
{
"type": "text",
"text": "Bienvenido a respond.io",
}Campo | Descripción | Validación |
tipo | Tipo de mensaje | Requerido. texto |
texto | Texto del mensaje | Requerido. Longitud máxima de 7,000 caracteres. |
Ejemplo de archivo multimedia
{
"type": "adjunto",
"adjunto": {
"tipo": "imagen|video|audio|archivo",
"url": "https://abc/japan. ng",
"mimeType": "image/png",
"fileName":"logo de empresa. ng",
"descripción": "último logo de la compañía"
}
}Campo | Descripción | Validación |
tipo | Tipo de mensaje | Requerido. adjunto. |
attachment.type | Tipo de archivo adjunto | Requerido. Tipos de archivos adjuntos disponibles: imagen, vídeo, audio y archivo. |
adjunto.url | URL | Requerido. Máx. 2,000 caracteres. Asegúrese de que es un enlace público para que los usuarios o los contactos puedan ver el contenido. |
adjunto.mimeTipo | Tipo Mime del archivo adjunto | Opcional |
nombre del archivo adjunto | Nombre del archivo | Opcional. El nombre del archivo debe incluir una extensión. Máximo 256 caracteres (incluyendo extensión de archivo). Enviar un archivo sin una extensión o con una extensión incorrecta podría causar que el contacto o el usuario no puedan abrir el archivo. |
Descripción del archivo adjunto | Descripción del archivo | Opcional. Máx. 256 caracteres. Sólo aplicable para attachment.type = imagen. |
Disposición de contenido encabezado en la respuesta HTTP debe ser el valor por defecto en línea)Ejemplo de ubicación
{
"type": "location",
"latitude": 0.123456,
"longitude": -0.1234,
"address": "Sky Suites, Jalan P. Ramlee, Kuala Lumpur, 50250 Kuala Lumpur, Wilayah Persekutuan Kuala Lumpur"
}Campo | Descripción | Validación |
tipo | Tipo de mensaje | Requerido. ubicación. |
latitud | Coordenadas | Requerido. Latitud (±90°) dentro de rangos válidos. |
longtitude | Coordenadas | Requerido. Longitud (±180°) dentro de rangos válidos. |
dirección | Dirección de ubicación | Opcional. Máx. 256 caracteres. |
Ejemplo de respuesta rápida
{
"type": "quick_reply",
"title": "Selecciona tu idioma preferido",
"respuestas": [
"Malayo",
"Inglés"
]
}Campo | Descripción | Validación |
tipo | Tipo de mensaje | Requerido. rápido_respuesta. |
título | Título de respuesta rápida | Requerido. Máx. 256 caracteres. |
respuestas | Responder texto | Requerido. Máximo 10 respuestas con un máximo de 256 caracteres para cada respuesta. |
Códigos de error
Error (HTTP Status → 4xx)
{
"error": {
"mensaje": "Mensaje de error"
}
}Capacidades de Broadcast
Es posible enviar mensajes de difusión a través de un canal personalizado conectado a respond.io, pero ciertas condiciones pueden causar que los mensajes no se envíen.
Con canales personalizados, no es posible detectar si una ventana de mensajería está abierta o cerrada. Tampoco es posible enviar mensajes etiquetados o de plantilla.
