WhatsApp¶
Solicitud HTTP para enviar vía WhatsApp¶
La trama para enviar un mensaje de WhatsApp es la siguiente:
POST https://send.obmessage.ai/api/v1/whatsapp
Authorization: {{API_KEY}}
Content-Type: application/json
Ejemplo de solicitud:
{
"phone": "+18099999999",
"contact_id": "uuid-del-contacto",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ref-001",
"group": "grupo-ventas",
"fields": [
{
"name": "nombre_campo",
"value": "valor",
"short": true
}
],
"campaign_id": "660e8400-e29b-41d4-a716-446655440000",
"senders": [
{
"name": "Mi Empresa",
"from": "+5491100000000",
"provider_customer_config_id": 1
}
],
"bidirectional": true,
"interaction_flow_id": "770e8400-e29b-41d4-a716-446655440000",
"interaction_flow_script_id": "880e8400-e29b-41d4-a716-446655440000"
}
Si desea realizar una integración de WhatsApp, contáctenos por correo.
Datos obligatorios¶
Los siguientes datos son requeridos para realizar un envío:
| Campo | Tipo | Descripción |
|---|---|---|
phone | string | Número telefónico al cual se enviará el mensaje de WhatsApp. Debe ser compatible con la recomendación E.164. |
template_id | uuid | Identificador de la plantilla de WhatsApp configurada en OBMessage que será utilizada para realizar el envío. |
Campos dinámicos
El campo fields también es obligatorio cuando la plantilla seleccionada contiene variables o elementos dinámicos que requieren valores para completar el mensaje.
Datos opcionales¶
Los siguientes campos son opcionales y pueden utilizarse de acuerdo con las necesidades de la integración:
| Campo | Tipo | Descripción |
|---|---|---|
contact_id | uuid | Identificador del contacto asociado al envío. |
reference | string | Referencia asociada al envío. Puede utilizarse para relacionar la solicitud con una referencia externa. |
group | string | Grupo asociado al envío. |
campaign_id | uuid | Identificador de la campaña asociada al envío. |
senders | array | Lista de remitentes asociados a la configuración del envío. |
bidirectional | boolean | Indica si el envío estará asociado a una configuración bidireccional. |
interaction_flow_id | uuid | Identificador del flujo de interacción asociado al envío. |
interaction_flow_script_id | uuid | Identificador del script del flujo de interacción asociado al envío. |
Ejemplo mínimo¶
Para enviar una plantilla que no contiene variables o elementos dinámicos, solo es necesario enviar phone y template_id:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
template_id¶
El campo template_id identifica la plantilla de WhatsApp previamente configurada en OBMessage.
{
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
La configuración de la plantilla, incluyendo su idioma, componentes, encabezados, cuerpo, botones y elementos multimedia, se administra previamente en OBMessage.
De esta forma, no es necesario enviar la estructura completa de la plantilla en cada solicitud.
fields¶
El campo fields permite proporcionar los valores utilizados por las variables o elementos dinámicos configurados en la plantilla.
Cuando la plantilla no utiliza variables, este campo puede omitirse.
Cuando la plantilla requiere variables o valores dinámicos, fields deberá incluir los elementos correspondientes.
Ejemplo:
{
"phone": "+18299999999",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [
{
"name": "nombre",
"value": "Juan",
"short": true
},
{
"name": "codigo",
"value": "ABC-123",
"short": true
}
]
}
Cada elemento de fields utiliza la siguiente estructura:
{
"name": "nombre_campo",
"value": "valor",
"short": true
}
| Campo | Tipo | Descripción |
|---|---|---|
name | string | Nombre del campo o variable configurada en la plantilla. |
value | string | Valor que será utilizado para reemplazar el campo o variable. |
short | boolean | Indicador asociado al campo enviado. |
Variables de plantilla
Si la plantilla requiere variables o elementos dinámicos, los valores correspondientes deben ser enviados mediante fields.
Los valores requeridos por la plantilla no deben enviarse vacíos.
Enviar una imagen mediante un campo dinámico¶
Cuando una plantilla utilice un enlace dinámico para una imagen, video o documento, el valor correspondiente puede enviarse mediante fields.
Ejemplo:
{
"phone": "+18099999999",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [
{
"name": "image_link",
"value": "https://example.com/image.png",
"short": true
}
]
}
contact_id¶
Permite asociar el envío a un contacto existente mediante su identificador.
{
"phone": "+5491123456789",
"contact_id": "uuid-del-contacto",
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
reference¶
Permite incluir una referencia externa relacionada con el envío.
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ref-001"
}
group¶
Permite asociar un grupo al envío.
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"group": "grupo-ventas"
}
campaign_id¶
Permite asociar el envío a una campaña mediante su identificador.
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"campaign_id": "660e8400-e29b-41d4-a716-446655440000"
}
senders¶
El campo senders permite incluir información relacionada con el remitente utilizado para el envío.
{
"senders": [
{
"name": "Mi Empresa",
"from": "+5491100000000",
"provider_customer_config_id": 1
}
]
}
Cada elemento puede contener los siguientes campos:
| Campo | Tipo | Descripción |
|---|---|---|
name | string | Nombre asociado al remitente. |
from | string | Número de origen asociado al remitente. |
provider_customer_config_id | integer | Identificador de la configuración del proveedor asociada al remitente. |
Ejemplo completo:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"senders": [
{
"name": "Mi Empresa",
"from": "+5491100000000",
"provider_customer_config_id": 1
}
]
}
Configuración bidireccional¶
El contrato permite asociar el envío a una configuración de interacción utilizando los siguientes campos:
| Campo | Tipo | Descripción |
|---|---|---|
bidirectional | boolean | Indica si el envío estará asociado a una interacción bidireccional. |
interaction_flow_id | uuid | Identificador del flujo de interacción asociado. |
interaction_flow_script_id | uuid | Identificador del script asociado al flujo de interacción. |
Ejemplo:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"bidirectional": true,
"interaction_flow_id": "770e8400-e29b-41d4-a716-446655440000",
"interaction_flow_script_id": "880e8400-e29b-41d4-a716-446655440000"
}
Ejemplo completo¶
{
"phone": "+5491123456789",
"contact_id": "uuid-del-contacto",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ref-001",
"group": "grupo-ventas",
"fields": [
{
"name": "nombre",
"value": "Juan",
"short": true
}
],
"campaign_id": "660e8400-e29b-41d4-a716-446655440000",
"senders": [
{
"name": "Mi Empresa",
"from": "+5491100000000",
"provider_customer_config_id": 1
}
],
"bidirectional": true,
"interaction_flow_id": "770e8400-e29b-41d4-a716-446655440000",
"interaction_flow_script_id": "880e8400-e29b-41d4-a716-446655440000"
}
Deprecación de whatsapp_template¶
El objeto whatsapp_template, utilizado anteriormente para enviar directamente la estructura completa de una plantilla de WhatsApp, se encuentra deprecado.
Contrato anterior¶
{
"phone": "+5491123456789",
"whatsapp_template": {
"name": "hello_world",
"language": {
"code": "en_US"
}
}
}
Nuevo contrato¶
Las nuevas integraciones deben utilizar template_id:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
Cuando la plantilla contiene variables o elementos dinámicos:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [
{
"name": "nombre",
"value": "Juan",
"short": true
}
]
}
Importante
whatsapp_template se encuentra deprecado y no debe utilizarse para desarrollar nuevas integraciones.
Las integraciones existentes que todavía utilicen `whatsapp_template` deberán migrarse al nuevo contrato basado en `template_id`.
La deprecación no establece una fecha específica de eliminación del contrato anterior, salvo que OFIMATIC comunique posteriormente una fecha de retiro.
Si desea asistencia para migrar una integración existente, contáctenos por correo.