Este tutorial te ayudará a crear tu propia integración con BotHelp. Puedes configurar BotHelp para que reciba notificaciones inmediatas sobre eventos específicos. Este tipo de notificación se denomina webhook y consiste en una simple solicitud HTTPS POST que BotHelp envía a tu servidor cuando ocurre un evento específico.
Configuración de webhooks
Actualmente, una cuenta de BotHelp solo puede tener un webhook que se suscribe por defecto a dos eventos: user_profile_viewed y conversation_closed. La suscripción a un webhook se puede configurar en la sección "Webhooks" del panel de control. Solo los administradores pueden añadir, editar o eliminar webhooks. Admitimos URLs de suscripción HTTPS para proteger las notificaciones.
Al hacer clic en "Añadir webhook", se mostrará un formulario para crearlo. Introduzca la URL del webhook, guárdela y se generará automáticamente un token para este webhook. El webhook con la URL especificada y el token generado se mostrará en la lista de webhooks de la página.
Se requiere un token para crear la firma de la solicitud. Cada devolución de llamada contendrá una firma en el JSON que se le pasa. La firma es HMAC con SHA256 y utiliza el token generado como clave y el JSON como valor. El resultado se envía como encabezado HTTP X-Wh-Sign para que el receptor pueda determinar el origen del mensaje.
Formato de webhook
Cada webhook es una solicitud POST HTTPS dirigida a la URL que proporcionaste en la sección Integraciones de tu cuenta. El cuerpo de la solicitud POST contiene información del webhook en formato JSON.
Cada webhook contiene las siguientes propiedades:
- Evento: indica el evento que activó el webhook. Valores posibles: user_profile_viewed, conversation_closed.
- event_timestamp – hora del evento que activó la devolución de llamada.
- Información adicional: información relacionada con un tipo de evento específico. Lea la sección "Tipos de eventos de webhook" a continuación.
Cuando su servidor recibe un webhook de BotHelp, debería responder con el código de estado HTTP 200. De lo contrario, BotHelp volverá a intentar enviar el webhook a su servicio varias veces a menos que reciba el código de estado HTTP 200 correcto (Pronto).
Nota: Los webhooks de BotHelp se envían con el encabezado HTTP Content-Type: application/json, así que asegúrese de que su servicio pueda manejar dichas solicitudes.
Tipos de eventos de webhook
Evento cerrado de conversación
Este tipo de evento se envía cada vez que un operador cierra la conversación con el cliente. El ejemplo del cuerpo POST de la solicitud de este evento es:
{
"evento": "conversación_cerrada",
"marca_de_tiempo_del_evento": 1400857494,
"conversación": {
"tipo": "conversación",
"id": "147",
"inicio_en": 1400850973,
"finalización_en": 1400857494
},
"usuario": {
"tipo": "usuario",
"id": “123123”,
“nick”: “Sr. Ivan”,
“correo electrónico”: “i.ivanov@gmail.com”,
“teléfono”: “+1123456789 ext. 923”,
"nombre": "Ivan Ivanov",
"tipo_canal": "viber",
"id_usuario_canal": "asddasdasd==",
"id_canal": "bothelp",
"último_contacto_en": 1397574667,
"primer_contacto_en": 1397574667,
"conversations_count": 179,
"avatar": "https://example.org/128Wash.jpg",
"custom_fields": {
"paid_subscriber": true,
"monthly_spend": 155.5,
"team_mates": 1
}
},
"assignee": {
"type": "agent", // o "team" si esta conversación fue asignada al equipo
"id": "25",
"email": "wash@hello.io", // o "" si el operador no es real. Este campo no está disponible si la conversación se asignó al equipo
"nombre": "Dmitry"
},
"autores": [ //operadores que participan en la conversación actual
{
"tipo": "agente",
"id": "2",
"correo electrónico": "",
"nombre": "Página de Vkontakte"
},
{
"tipo": "agente",
"id": "4",
"correo electrónico": "",
"nombre": "Página de Facebook"
},
{
"tipo": "agente",
"id": "25",
"correo electrónico": "wash@hello.io",
"nombre": "Dmitry"
}
],
"mensajes": [
{
"autor": {
"tipo": "usuario",
"id": "123123"
},
"id": "344",
"tipo": "texto",
"texto": "Hola",
"marca de tiempo": 1358937653
},
{
"autor": {
"tipo": "usuario",
"id": "123123"
},
"id": "417",
"tipo": "documento",
"datos": {
"enlace": 'http://example.com/document.pdf',
"nombre": 'SimpleDocument.pdf',
"tamaño": 24123
},
"marca de tiempo": 1358937661
},
{
"autor": {
"tipo": "agente",
"id": "25"
},
"id": "420",
"tipo": "imagen",
"datos": "http://example.org/image.jpg",
"marca de tiempo": 1358937661
},
{
"autor": {
"tipo": "agente",
"id": "25"
},
"id": "425",
"tipo": "pegatina",
"datos": "http://example.org/pegatina1.png",
"marca de tiempo": 1358937661
},
{
"autor": {
"tipo": "agente",
"id": "25"
},
"id": "450",
"tipo": "video",
"datos": "http://example.org/video1.mp4",
"marca de tiempo": 1358937661
},
{
"autor": {
"tipo": "usuario",
"id": "123123"
},
"id": "457",
"tipo": "ubicación",
"datos": {
"longitud": 25.0123323,
"latitud": 50.1748532
},
"marca de tiempo": 1358937661
},
{
"autor": {
"tipo": "usuario",
"id": "123123"
},
"id": "460",
"tipo": "contacto",
"datos": {
"nombre": "Ivan I.",
"número_de_teléfono": "+123321123"
},
"marca_de_tiempo": 1358937661
}
]
}
Si tienes alguna pregunta no dudes en preguntarnos en el chat.