📌Canal Personalizado

Integrar la aplicación de mensajería de terceros en Okeybot.

Esta función se encuentra actualmente en fase Beta. ¡Si tiene algún problema, póngase en contacto con nosotros aquí!

Consejos: También le proporcionamos un ejemplo de canal personalizado que puede intentar implementar en su servidor.

Flujo del canal personalizado

¿Cómo funciona?

Recibir mensaje:

Para recibir un mensaje a través de un canal personalizado, se deben seguir los siguientes pasos:

1. Cuando un contacto intenta enviar un mensaje, el proveedor de servicios de mensajería llamará a su servidor de integración personalizado con la carga útil del mensaje (consulte la documentación de la API del proveedor de servicios de mensajería para obtener referencia).

2. Su servidor de integración personalizado recibirá el mensaje y lo publicará en Okeybot (en formato de Okeybot).

3. Okeybot recibirá la solicitud post, guardará el mensaje y lo mostrará en el módulo de mensajería.

Enviar mensaje:

Para enviar un mensaje a través de un canal personalizado, se deben seguir los siguientes pasos:

1. Cuando un Usuario/Flujo de trabajo / Difusión intente enviar un mensaje, Okeybot llamará a su servidor de integración personalizado con la carga útil del mensaje (en formato de Okeybot).

2. Su servidor de integración personalizado recibirá el mensaje y lo enviará al proveedor de servicios de mensajería en el formato que requiera (consulte la documentación de la API del proveedor de servicios de mensajería para obtener referencia).

3. El proveedor de servicios de mensajería recibirá el Webhook y confirmará si el mensaje se ha entregado correctamente. Consejos, si el mensaje no se entrega correctamente, puede intentar agregar un mecanismo de reintento en su servidor de integración personalizado.

Configuración

Paso 1: Crear un canal

1. En la plataforma Okeybot, vaya a Configuración > Canales y haga clic en el botón AGREGAR CANAL.

2. Seleccionar Canal Personalizado (Custom Channel).

3. Introduzca la URL base de la API.

4. Seleccione el tipo de ID para el canal y haga clic en SIGUIENTE. Este ID tiene el propósito de identificar al usuario y se utilizará para comunicarse con su servidor de integración personalizado. Hay dos tipos de IDs:

   1. Número de teléfono: Utilícelo si el proveedor de servicios de mensajería reconoce a los contactos en función de su número de teléfono. Formato de muestra: + 60177872890

   2. ID personalizado: Utilícelo si el proveedor de servicios de mensajería reconoce contactos en función de un ID generado a medida.

      1. La longitud máxima de caracteres es de 50.

      2. A-Z, a-z, 0-9, _ , =, + , / y @ están permitidos.

5. El siguiente cuadro de diálogo proporcionará el ID de canal, el token de API y la URL del Webhook, p. ej.

   1. ID de canal: gfd8g7fd89dgfd

   2. API Token: aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd

   3. URL del Webhook: https://okeybot.com/custom/webhook

Consejos: Usar el tipo de ID de número de teléfono te permite iniciar una conversación y enviar el primer mensaje a un contacto.

Paso 2: Pasar mensajes a Okeybot

La URL del Webhook se utiliza para PUBLICAR los Mensajes, Ecos de Mensajes y Recibos de Mensajes en la plataforma Okeybot.

El siguiente código llamará al webhook en la plataforma Okeybot y estará creando el contacto (si no existe) y guardando el mensaje contra el contacto.

curl -X POST \
  **<https://app.okeybot.com/custom/webhook**> \
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "channelId": "gfd8g7fd89dgfd",
  "contactId": "[phone]",
  "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": "[e-mail]",
    "phone": "[phone]",
    "language": "es"
  }
}'

Campos

Campo	Descripción	Validación
channelId	ID único del canal	Requerido. Campo único. Es generado por Okeybot.
contactId	Id único de contacto	Requerido. ID único de contacto de Okeybot. Max 50 carcteres.
events.type	Tipo Evento	Requerido. Mensaje.
events.mId	ID de Mensaje	Requerido. ID único de mensaje. Max 50 caracteres.
events.timestamp	Época única Tiempo(millisegundos)	Requerido. Hora del evento que activó la devolución de llamada.
events.message.type	Tipo mensaje	Requerido. Tipos de mensajes disponibles: texto, archivo adjunto, ubicación y respuesta rápida. Consulte la sección de tipo de mensaje para otras muestras de tipo de mensaje.
events.message.text	Texto del mensaje	Requerido. Longitud máxima de 7,000 caracteres.
contact.firstName	Nombre	Opcional. Max 50 caracteres.
contact.lastName	Apellidos	Opcional. Max 50 caracteres.
contact.profilePic	URL de foto de perfil	Opcional. El tamaño de la imagen del avatar no debe ser mayor de 100 kb. Recomendado 720x720
contact.locale	Código local	Opcional. Consulte aquí la lista de valores.
contact.countryCode	Código del país	Opcional. Código de país de 2 letras - Código ISO ALFA - 2.
contact.timezone	Huso horario	Opcional. (min: -24) (max: 24)
contact.email	Correo electrónico	Opcional. Max 50 caracteres.
contact.phone	Número de teléfono	Opcional. Max 18 caracteres.
contact.language	Idioma	Opcional. ISO 639-1

Respuesta de éxito (Estado HTTP → 200)

"OK"

Paso 3: Manejar mensajes salientes desde Okeybot

Okeyot llamará al siguiente punto final <URL de base de API > / mensaje

Importante: Asegúrese de implementar el código de mensaje saliente en la ruta / message de su servidor web.

Aquí está el ejemplo de cURL de Okeybot llamando al punto final.

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": "[phone]",
	"message": {
		"type": "text",
		"text": "Hello World"
	}
}'

Respuesta de éxito (Estado HTTP → 200)

{
	"mId": "1640141607842"
}

La autenticación debe realizarse en el punto final antes de pasar el mensaje al Proveedor de Servicios de mensajería. Aquí hay un ejemplo de middleware express.

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

const validateToken = (req, res, next) => {
    const apiToken = <<API Token>>
    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
};

Consejos: También le proporcionamos un ejemplo de canal personalizado que puede intentar implementar en su servidor.

Tipo de mensaje

Muestra de texto

{
  "type": "text",
  "text": "Welcome to Okeybot",
}

Campos

Campo	Descripción	Validación
tipo	Tipo de mensaje	Requerido. Texto.
texto	Texto de mensaje	Requerido. Longitud máxima de 7,000 caracteres.

Ejemplo para archivo multimedia

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

Campo	Descripción	Validación
type	Tipo de mensaje	Requerido. Adjunto
attachment.type	Tipo de adjunto	Requerido. Tipo de adjusntos disponibles: imagen, video, audio y archivo.
attachment.url	URL	Requerido. Max 2,000 caracteres. Asegúrese de que sea un enlace público para que los usuarios o contactos puedan ver el contenido.
attachment.mimeType	Tipo Mime del archivo adjunto	Opcional
attachment.fileName	Nombre del archivo	Opcional. El nombre del archivo debe incluir una extensión. Max 256 caracteres (incluyendo extensión del archivo). Enviar un archivo sin extensión o con una extensión incorrecta puede hacer que el contacto o el usuario no pueda abrir el archivo.
attachment.description	Descripción del archivo	Opcional. Max 256 caracteres. Solo aplicable para attachment.type = imagen

Ejemplo para localizació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
type	Tipo de mensaje	Requerido. Localización
latitude	Coordenadas	Requerido. Latitud (±90°) dentro de rangos válidos.
longitude	Coordenadas	Requerido. Longitud (±180°) dentro de rangos válidos.
address	Dirección de ubicación	Opcional. Max 256 caracteres.

Ejemplo para respuesta rápida

{
  "type": "quick_reply",
  "title": "Select your preferred language",  
  "replies": [
    "Malay",
    "Spanish"
  ]
}

Campo	Descripción	Validación
type	Tipo de mensaje	Requerido. respuesta_rápida
title	Título de respuesta rápida	Requerido. Max 256 caracteres.
replies	Texto de respuesta	Requerido. Max 10 respuestas con un máximo de 256 caracteres por cada respuesta

Solucionador de problemas

Esta función se encuentra actualmente en fase Beta. ¡Si tiene algún problema, póngase en contacto con nosotros aquí!