WhatsApp Notifications API

Official documentation for using Lovi’s API with WhatsApp via Postman

Introduction

This section provides the official documentation for using Lovi’s API with WhatsApp via Postman. It includes detailed instructions on how to set up and test API requests for WhatsApp integration, ensuring smooth communication through the platform. Authentication is performed using tokens that enable basic authentication for the API services. For more details on how to authenticate, please refer to the Authentication page.

📣 Send Notification

To send a notification via the Lovi API, make a POST request to the endpoint with the necessary parameters and authentication.

Method: POST Method: JSON

Endpoint

POST https://cloud.lovi.ai/functions/v1/notify

Query Parameters

Parameter	Required	Description
access_key	Yes	Your unique API access key.
unflatten	No	If set to true, the body must contain flat variables (no nested objects). If set to false or omitted, the body can contain nested objects.

When unflatten=true, the body must be flat, meaning no nested objects are allowed.

Headers

Key	Value	Required	Description
apikey	your-api-key	Yes	Your unique API key for authentication.

The apikey header should contain your API key, which is necessary for authentication and access to the API.

Body Request

The body of the request contains the notification details.

When unflatten=false or the parameter is omitted, you can use nested objects, as shown in the following example.

{
  "components_push": {
    "position_type_number": "example"
  },
  "contact": {
    "number": "34123123123",
    "name": "John Doe"
  },
  "language_template": "en_US",
  "name_template": "your_template",
  "recipient_id": "34123123123",
  "notification_type": "marketing",
  "campaign_name": "Webservice Test"
}

❗When unflatten=true, you must concatenate the main key with the subkey. This ensures the structure remains flat, and nested objects are not supported.

Example with nested objects (not allowed when unflatten=true):

{
  "contact": {
    "number": "34123123123",
    "name": "John Doe"
  },
  "language_template": "en_US"
}

Example with a flat structure (required when unflatten=true). Here the keys are concatenated (e.g., contact.number), which is the correct format when unflatten=true:

{
  "contact.number": "34123123123",
  "contact.name": "John Doe",
  "language_template": "en_US"
}

Parameter	Required	Description
components_push	No	Optional. The components_push parameter is not required by default, but it may be necessary depending on the template being used. It must follow the structure components_push.{position}_{type}_{number}. For more information, see below.
contact	Yes	The contact parameter is an object. For more information about its fields, see below.
language_template	Yes	Language code for the template (e.g., es_ES for Spanish).
name_template	Yes	Name of the template that will be used for the message (e.g., your_template).
recipient_id	Yes	ID or phone number of the recipient who will receive the notification. Example: 34123123123.
notification_type	Yes	Type of notification. (e.g., marketing, transactional).
campaign_name	Yes	Name of the campaign this notification belongs to (e.g., “Webservice Test”).

🧩 Dynamic placeholders ({{variable}})

In your template text, you can use placeholders like {{variable}} to dynamically inject a value when the message is sent.

These placeholders will be replaced with the corresponding value provided in the payload. The system expects only one type of input per message: either a variable or static text — you cannot mix both. The system will look for parameters that match the placeholder name — either from the contact object or from any other custom parameter.

Additionally, you can only use one variable per message — using multiple variables in the same field is not allowed.

✅ Example:

{
  "contact.name": "Laura",
  "contact.course": "Nursing Assistant Technician",
  "components_push.body_text_0": "{{name}}",
  "components_push.body_text_1": "{{course}}",
  "components_push.body_text_2": "Welcome to our academy!"
}

❌ Invalid examples (not allowed)

The following example is incorrect because it combines plain text with a placeholder in the same field:

{
  "components_push.body_text_0": "Hi {{name}}, your course starts soon!"
}

The following example is incorrect because it uses two variables in the same field:

{
  "components_push.body_text_0": "{{name}} - {{course}}"
}

📌Keep in mind:

• The variable name inside {{ }} must match the key in the payload (flattened, if needed).
• You can use as many placeholders as you need, depending on what your template allows. But remember, you cannot use two variables together in the same field. The system only supports one variable per field. Each message field can contain either a single placeholder or static text, but not a combination of multiple variables.
• You must choose between a placeholder or a fixed message — combining both is not allowed.
• This system allows for personalized messages at scale.

components_push Parameter

This parameter allows you to include dynamic content, static text, or media in your message template. It is not required by default, but it may be necessary depending on the template you are using.

It must follow the following key structure: components_push.{position}_{type}_{number}: "value"

Where:

• position (required): Indicates the component’s location within the template. Valid values are: header, body, footer, or button.

• type (required): Describes the type of parameter, such as text, image, document, etc. The exact value depends on the component and how the template was defined.

• number (required): An integer that indicates the parameter’s position in the template.

• value (required): It must be type string or string, it contains the value of the parameter.

The value assigned to this key will be the content to insert into the template (e.g., a text string, an image URL, or the name of an uploaded file).

Possible values by field:

Field (position)	Accepted type values
header	text, document, image, video
body	text
footer	text
button	url, payload

Example

{
  "components_push.body_text_0": "Lorem Ipsum",
  "components_push.header_image_1": "https://example.com/image.jpg"
}

In this example:

body_text_0 refers to the first dynamic text parameter in the body.

header_image_1 refers to an image placed in the template’s header.

contact Parameter

The contact parameter is an object that contains all the details related to the recipient of the message. It is mandatory to include the contact.number field, as this is the phone number of the person who will receive the notification.

However, the contact object can contain additional optional fields, such as the name of the contact, to further personalize the message.

Required Fields in the contact Object:

• contact.number (String): The phone number of the contact. This field is required and should be in international format without the + symbol (e.g., 34123123123).

Optional Fields in the contact Object:

Here are some examples:

• contact.name (String): The name of the contact.
• contact.address (String): The address of the contact.
• You can include as much information as needed within the contact object, depending on the level of personalization required by the template.

⚠️ Media Attachments:

Currently, the API only supports sending links for media (images, documents, and videos). You cannot directly upload media files, but you can include URLs to media hosted externally.

Example of sending a media link:

{
  "components_push.header_image_1": "https://example.com/image.jpg",
  "contact.number": "34123123123",
  "contact.name": "John Doe",
  "language_template": "en_US",
  "name_template": "your_template",
  "recipient_id": "34123123123",
  "notification_type": "marketing",
  "campaign_name": "Webservice Test"
}

Response

When the request is successful, the response will contain the following message:

{
  "message": "Registration successful"
}

---

📚 Tips for Development

• Use access_key when available in query parameters.
• Use apikey or Authorization: Bearer in headers depending on endpoint security.
• For endpoints that deal with voice or widgets, session_id is crucial.
• Store and handle tokens securely.
• Prior validations: Validate data before sending it to the API to avoid errors.
• Testing: Test in a development environment before implementing in production.
• Permission control: Limit token generation to users with administrator permissions.