WhatsApp¶
HTTP request to send via WhatsApp¶
The request to send a WhatsApp message is as follows:
POST https://send.obmessage.ai/api/v1/whatsapp
Authorization: {{API_KEY}}
Content-Type: application/json
Request example:
{
"phone": "+18099999999",
"contact_id": "contact-uuid",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ref-001",
"group": "sales-group",
"fields": [
{
"name": "field_name",
"value": "value",
"short": true
}
],
"campaign_id": "660e8400-e29b-41d4-a716-446655440000",
"senders": [
{
"name": "My Company",
"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"
}
If you would like to integrate with WhatsApp, contact us by email.
Required data¶
The following fields are required to send a message:
| Field | Type | Description |
|---|---|---|
phone | string | Telephone number to which the WhatsApp message will be sent. It must use a format compatible with the E.164 recommendation. |
template_id | uuid | Identifier of the WhatsApp template configured in OBMessage that will be used to send the message. |
Dynamic fields
The fields property is also required when the selected template contains variables or dynamic elements that require values to complete the message.
Optional data¶
The following fields are optional and can be used according to the integration requirements:
| Field | Type | Description |
|---|---|---|
contact_id | uuid | Identifier of the contact associated with the message. |
reference | string | Reference associated with the request. It can be used to associate the message with an external reference. |
group | string | Group associated with the request. |
campaign_id | uuid | Identifier of the campaign associated with the message. |
senders | array | List of senders associated with the message configuration. |
bidirectional | boolean | Indicates whether the message is associated with a bidirectional configuration. |
interaction_flow_id | uuid | Identifier of the interaction flow associated with the message. |
interaction_flow_script_id | uuid | Identifier of the interaction flow script associated with the message. |
Minimum request¶
To send a template that does not contain variables or dynamic elements, only phone and template_id are required:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
template_id¶
The template_id field identifies the WhatsApp template previously configured in OBMessage.
{
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
The template configuration, including its language, components, headers, body, buttons, and multimedia elements, is managed in OBMessage beforehand.
This means the complete template structure does not need to be submitted with each request.
fields¶
The fields property provides the values used by variables or dynamic elements configured in the template.
When the template does not use variables, this property can be omitted.
When the template requires variables or dynamic values, fields must contain the corresponding elements.
Example:
{
"phone": "+18299999999",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [
{
"name": "name",
"value": "John",
"short": true
},
{
"name": "code",
"value": "ABC-123",
"short": true
}
]
}
Each fields element uses the following structure:
{
"name": "field_name",
"value": "value",
"short": true
}
| Field | Type | Description |
|---|---|---|
name | string | Name of the field or variable configured in the template. |
value | string | Value used to replace the field or variable. |
short | boolean | Indicator associated with the submitted field. |
Template variables
If the template requires variables or dynamic elements, the corresponding values must be provided through fields.
Values required by the template must not be empty.
Sending an image using a dynamic field¶
When a template uses a dynamic link for an image, video, or document, the corresponding value can be provided through fields.
Example:
{
"phone": "+18099999999",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [
{
"name": "image_link",
"value": "https://example.com/image.png",
"short": true
}
]
}
contact_id¶
Allows the message to be associated with an existing contact using its identifier.
{
"phone": "+5491123456789",
"contact_id": "contact-uuid",
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
reference¶
Allows an external reference to be associated with the message.
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ref-001"
}
group¶
Allows a group to be associated with the message.
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"group": "sales-group"
}
campaign_id¶
Allows the message to be associated with a campaign using its identifier.
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"campaign_id": "660e8400-e29b-41d4-a716-446655440000"
}
senders¶
The senders property allows sender information to be included in the request.
{
"senders": [
{
"name": "My Company",
"from": "+5491100000000",
"provider_customer_config_id": 1
}
]
}
Each element can contain the following fields:
| Field | Type | Description |
|---|---|---|
name | string | Name associated with the sender. |
from | string | Origin number associated with the sender. |
provider_customer_config_id | integer | Identifier of the provider configuration associated with the sender. |
Complete example:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"senders": [
{
"name": "My Company",
"from": "+5491100000000",
"provider_customer_config_id": 1
}
]
}
Bidirectional configuration¶
The contract allows the message to be associated with an interaction configuration using the following fields:
| Field | Type | Description |
|---|---|---|
bidirectional | boolean | Indicates whether the message is associated with a bidirectional interaction. |
interaction_flow_id | uuid | Identifier of the associated interaction flow. |
interaction_flow_script_id | uuid | Identifier of the script associated with the interaction flow. |
Example:
{
"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"
}
Complete example¶
{
"phone": "+5491123456789",
"contact_id": "contact-uuid",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ref-001",
"group": "sales-group",
"fields": [
{
"name": "name",
"value": "John",
"short": true
}
],
"campaign_id": "660e8400-e29b-41d4-a716-446655440000",
"senders": [
{
"name": "My Company",
"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"
}
whatsapp_template deprecation¶
The whatsapp_template object previously used to submit the complete WhatsApp template structure is deprecated.
Previous contract¶
{
"phone": "+5491123456789",
"whatsapp_template": {
"name": "hello_world",
"language": {
"code": "en_US"
}
}
}
New contract¶
New integrations must use template_id:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000"
}
When the template contains variables or dynamic elements:
{
"phone": "+5491123456789",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [
{
"name": "name",
"value": "John",
"short": true
}
]
}
Important
whatsapp_template is deprecated and must not be used when developing new integrations.
Existing integrations that still use `whatsapp_template` should migrate to the new `template_id`-based contract.
Deprecation does not establish a specific removal date for the previous contract unless OFIMATIC communicates a retirement date at a later time.
If you need assistance migrating an existing integration, contact us by email.