omniatix-chat-webhook-integration
Guía completa para configurar y gestionar webhooks en OmniAtix Chat. Recibe notificaciones en tiempo real sobre eventos de tu cuenta.
Documentación de Webhooks de OmniAtix Chat
Esta documentación te guiará a través del proceso de configuración y gestión de webhooks en tu cuenta de OmniAtix Chat. Los webhooks te permiten recibir notificaciones en tiempo real sobre diversos eventos que ocurren en tu cuenta.
La URL base para todas las peticiones de la API es: https://app.omniatix.chat
Gestión de Webhooks
A continuación se detallan los endpoints para administrar los webhooks de tu cuenta.
Listar todos los Webhooks
Obtiene una lista de todos los webhooks configurados en la cuenta.
GET /api/v1/accounts/{account_id}/webhooks
Autorización
| Tipo | En | Nombre | Requerido | Descripción |
|---|---|---|---|---|
| Header | header | Api-Access-Token | Sí | Token de acceso a la API obtenido desde el perfil del usuario. |
Parámetros de Ruta
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
account_id | integer | Sí | El ID numérico de la cuenta. |
Respuesta Exitosa (200 OK)
Devuelve un array de objetos webhook.
Cuerpo de la Respuesta (application/json)
[
{
"id": 123,
"url": "https://example.com/webhook",
"subscriptions": [
"conversation_created",
"conversation_status_changed"
],
"account_id": 1
},
{
"id": 124,
"url": "https://another-example.com/webhook",
"subscriptions": [
"message_created"
],
"account_id": 1
}
]
Añadir un Webhook
Crea una nueva suscripción de webhook en la cuenta.
POST /api/v1/accounts/{account_id}/webhooks
Autorización
| Tipo | En | Nombre | Requerido | Descripción |
|---|---|---|---|---|
| Header | header | Api-Access-Token | Sí | Token de acceso a la API. |
Parámetros de Ruta
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
account_id | integer | Sí | El ID numérico de la cuenta. |
Cuerpo de la Petición (application/json)
| Nombre | Tipo | Descripción | Ejemplo |
|---|---|---|---|
url | string | La URL a la que se deben enviar los eventos. | "https://example.com/webhook" |
subscriptions | enum<string>[] | La lista de eventos a los que deseas suscribirte. | ["conversation_created", "conversation_status_changed"] |
Ejemplo de Petición con cURL
curl --request POST \
--url https://app.omniatix.chat/api/v1/accounts/{account_id}/webhooks \
--header 'Content-Type: application/json' \
--header 'Api-Access-Token: <tu-api-key>' \
--data '{
"url": "https://example.com/webhook",
"subscriptions": [
"conversation_created",
"conversation_status_changed"
]
}'
Respuestas
200 OK: Devuelve el objeto webhook creado.401 Unauthorized: ElApi-Access-Tokenes inválido o no se ha proporcionado.
Actualizar un Webhook
Actualiza un objeto webhook existente en la cuenta.
PATCH /api/v1/accounts/{account_id}/webhooks/{webhook_id}
Autorización
| Tipo | En | Nombre | Requerido | Descripción |
|---|---|---|---|---|
| Header | header | Api-Access-Token | Sí | Token de acceso a la API. |
Parámetros de Ruta
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
account_id | integer | Sí | El ID numérico de la cuenta. |
webhook_id | integer | Sí | El ID numérico del webhook a actualizar. |
Cuerpo de la Petición (application/json)
| Nombre | Tipo | Descripción | Ejemplo |
|---|---|---|---|
url | string | (Opcional) La nueva URL a la que se enviarán los eventos. | "https://new-example.com/webhook" |
subscriptions | enum<string>[] | (Opcional) La nueva lista de eventos a los que suscribirse. | ["message_created", "message_updated"] |
Eventos disponibles para suscripción:
conversation_created, conversation_status_changed, conversation_updated, message_created, message_updated, contact_created, contact_updated, webwidget_triggered.
Respuesta Exitosa (200 OK)
Devuelve el objeto webhook actualizado.
Eliminar un Webhook
Elimina permanentemente un webhook de la cuenta.
DELETE /api/v1/accounts/{account_id}/webhooks/{webhook_id}
Autorización
| Tipo | En | Nombre | Requerido | Descripción |
|---|---|---|---|---|
| Header | header | Api-Access-Token | Sí | Token de acceso a la API. |
Parámetros de Ruta
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
account_id | integer | Sí | El ID numérico de la cuenta. |
webhook_id | integer | Sí | El ID numérico del webhook a eliminar. |
Respuesta Exitosa (200 OK)
La respuesta no contiene cuerpo, indicando que la eliminación fue exitosa.
Carga Útil del Webhook (Payload)
OmniAtix Chat enviará una solicitud POST con la siguiente carga útil a las URL configuradas para varias actualizaciones en tu cuenta.
Ejemplo de Carga Útil de un Webhook
{
"event": "message_created",
"id": "1",
"content": "Hola",
"created_at": "2020-03-03 13:05:57 UTC",
"message_type": "incoming",
"content_type": "text",
"content_attributes": {},
"source_id": "",
"sender": {
"id": "1",
"name": "Agente",
"email": "[email protected]"
},
"contact": {
"id": "1",
"name": "nombre-contacto"
},
"conversation": {
"display_id": "1",
"additional_attributes": {
"browser": {
"device_name": "Macbook",
"browser_name": "Chrome",
"platform_name": "Macintosh",
"browser_version": "80.0.3987.122",
"platform_version": "10.15.2"
},
"referer": "http://www.omniatix.chat",
"initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)"
}
},
"account": {
"id": "1",
"name": "OmniAtix Chat"
}
}
Eventos de Webhook Soportados
OmniAtix Chat publica varios eventos en los endpoints de webhook configurados.
conversation_created: Se dispara cuando se crea una nueva conversación en la cuenta.conversation_updated: Se dispara cuando hay un cambio en cualquiera de los atributos de la conversación.conversation_status_changed: Se dispara cuando cambia el estado de la conversación.message_created: Se dispara cuando se crea un mensaje en una conversación.message_updated: Se dispara cuando se actualiza un mensaje en una conversación.webwidget_triggered: Se dispara cuando el usuario final abre el widget de chat en vivo.conversation_typing_on: Se dispara cuando un agente comienza a escribir en una conversación.conversation_typing_off: Se dispara cuando un agente deja de escribir o abandona la ventana de conversación.
Estructura de Objetos
La carga útil de un evento puede incluir cualquiera de los siguientes objetos.
Account
{
"id": "integer",
"name": "string"
}```
### `Inbox`
```json
{
"id": "integer",
"name": "string"
}
Contact
{
"id": "integer",
"name": "string",
"avatar": "string",
"type": "contact",
"account": {
// <...Objeto Cuenta>
}
}
User
{
"id": "integer",
"name": "string",
"email": "string",
"type": "user"
}
Conversation
{
"additional_attributes": {
"browser": {
"device_name": "string",
"browser_name": "string",
"platform_name": "string",
"browser_version": "string",
"platform_version": "string"
},
"referer": "string",
"initiated_at": {
"timestamp": "iso-datetime"
}
},
"can_reply": "boolean",
"channel": "string",
"id": "integer",
"inbox_id": "integer",
"contact_inbox": {
"id": "integer",
"contact_id": "integer",
"inbox_id": "integer",
"source_id": "string",
"created_at": "datetime",
"updated_at": "datetime",
"hmac_verified": "boolean"
},
"messages": ["Array de objetos de mensaje"],
"meta": {
"sender": {
// Objeto Contacto
},
"assignee": {
// Objeto Usuario
}
},
"status": "string",
"unread_count": "integer",
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
"account_id": "integer"
}
Message
{
"id": "integer",
"content": "string",
"message_type": "integer",
"created_at": "unix-timestamp",
"private": "boolean",
"source_id": "string / null",
"content_type": "string",
"content_attributes": "object",
"sender": {
"type": "string - contact/user",
// Objeto Usuario o Contacto
},
"account": {
// Objeto Cuenta
},
"conversation": {
// Objeto Conversación
},
"inbox": {
// Objeto Bandeja de Entrada
}
}