Send

Use this feature to send an HSM to your customers through your preferred bot. The API will handle the delivery of the messages to the recipients with your preset template.

When you send a message you can do even more, you can send buttons and action payloads to give users more interactive engagement through flow triggers, extra choices, extra content, or specific information.

Ensure that your customers have opted in to receive messages from your business

Send a message

POST https://api.jelou.ai/v2/whatsapp/:botId/hsm

Send HSM message to WhatsApp users.

Request Body

Name	Type	Description
mediaUrl	string	String that defines media url. Is required for image\|document type otherwise not needed.
fileName	string	File name is optional for document type otherwise not needed.
type	string	String that defines hsm type, it could be text\|image\|document\|video. This field is required for sending image or document. If you don't specify type the default value is text.
language	string	Language code
elementName	string	Element name
parameters	array	Array of strings containing the values to replace in the hsm template.
destinations	array	Array of strings representing the numbers of the clients to send the hsm.
buttonPayloads	array	Button Payloads structure. Required when the template has quick reply buttons
actions	object	It is a payload with the HSM configuration information. Actions payload.
dynamicUrlParameter	array	Required when the HSM template have dynamic URL. Array of strings containing the values to replace in the dynamic URL.

Name

Type

Description

mediaUrl

string

String that defines media url. Is required for image|document type otherwise not needed.

fileName

string

File name is optional for document type otherwise not needed.

type

string

String that defines hsm type, it could be text|image|document|video. This field is required for sending image or document. If you don't specify type the default value is text.

language

string

Language code

elementName

string

Element name

parameters

array

Array of strings containing the values to replace in the hsm template.

destinations

array

Array of strings representing the numbers of the clients to send the hsm.

buttonPayloads

array

Button Payloads structure. Required when the template has quick reply buttons

actions

object

It is a payload with the HSM configuration information. Actions payload.

dynamicUrlParameter

array

Required when the HSM template have dynamic URL. Array of strings containing the values to replace in the dynamic URL.

An array of objects, each object has the information of the id of the template and the destination

[
  {
    "id": "09d0fc2b-59d9-4149-9543-adfa92586615",
    "destination": "593999999999"
  }
]

Error sending the template. The template does not exist or is not approved by WhatsApp.

{
  "message": [
    "Template does not exist"
  ],
  "status": "failed",
  "_metadata": {
    "error": {},
    "body": {
      "destinations": [
        {
          "destination": "5939XX48X47X"
        }
      ],
      "parameters": [
        "Omar",
        "123456"
      ],
      "elementName": "call_to_action_twice",
      "code": "es",
      "type": "text",
      "botId": "+123456789000",
      "botName": "Jelou Dev WhatsApp"
    }
  },
  "error": {}
}

The botId used to send the template does not exist.

{
  "message": [
    "The Bot could not be found at the moment."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1019",
    "key": "BOT_NOT_FOUND",
    "description": "Error to be thrown when trying to get a Bot.",
    "developerMessages": {
      "es": "El botId no se encuentra en la base de datos o ha sido eliminado.",
      "en": "The botId is not found in the database or has been deleted.",
      "pt": "A botId não é encontrada no banco de dados ou foi apagada."
    },
    "clientMessages": {
      "es": "El Bot no se pudo encontrar por el momento.",
      "en": "The Bot could not be found at the moment.",
      "pt": "A Bot não pôde ser encontrada no momento."
    }
  }
}

Validation error, occurs when the sent payload does not follow the format validations for each field of the payload.

{
  "message": [
    "Los valores ingresados no son correctos."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E0422",
    "key": "VALIDATOR_ERROR",
    "description": "Error to be thrown when cannot process request because of incoming values",
    "developerMessages": {
      "es": "Los valores del request no son correctos para ser procesados.",
      "en": "The request values are not correct for processing."
    },
    "clientMessages": {
      "es": "Los valores ingresados no son correctos.",
      "en": "The values entered are not correct."
    }
  },
  "validationError": {
    "parameters": [
      {
        "en": "The number of parameters is incorrect.",
        "es": "El número de parámetros es incorrecto.",
        "pt": "O número de parâmetros está incorreto."
      }
    ]
  }
}

Server error trying to process template submission request.

{
  "message": [
    "We are having trouble processing your request. Please try again later."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E0000",
    "key": "UNKNOWN_ERROR",
    "description": "Error to be thrown when it couldn't be determined the reason of failure",
    "developerMessages": {
      "es": "Error inesperado occurido, revisar logs.",
      "en": "Unexpected error occurred, check logs."
    },
    "clientMessages": {
      "es": "Estamos teniendo problemas procesando la solicitud. Por favor intenta mas tarde.",
      "en": "We are having trouble processing your request. Please try again later."
    }
  }
}

Button Payload

You can use the following structure in the buttonPayloads field when the template has quick reply buttons:

To send FLOWS:

[
  {
    "flowId": 1,
    "action": "More information"
  },
  {
    "flowId": 2,
    "action": "Contact agency"
  }
]

In this case, each object must have two keys: flowId, which refers to the flow that the button should follow (please contact the Jelou team for flowId information), and action, which is the button’s label.

To send SKILLS:

[
  {
    "type": "edge",
    "action": "Yes",
    "skillId": "1"
  },
  {
    "type": "edge",
    "action": "Reschedule",
    "skillId": "2"
  },
  {
    "type": "edge",
    "action": "Cancel",
    "skillId": "3"
  }
]

Here, each object must have the keys type, action, and skillId. action defines the button’s label, and skillId indicates the ID of the skill that the button should trigger (please contact the Jelou team for skillId information).

Actions payload

The following configurations are supported by HSM.

1. Configuration to a specific flow

This feature is used to redirect users to a specific flow based on the response. The id field corresponds to the flow ID. To get the flowId check the Flow section.

{
  "actions": {
    "setFlow": {
      "id": 2222
    }
  }
}

Set up a flow for each of the HSM options. The settings for each of the options must go in the options array. To get the flowId check the Flow section.

Fields	Description	Data type
index	Option number	Integer
type	Configuration type. Must be flow	String
flowId	Flow ID	Integer
tittle	Option text. The text must be the same as the one in the HSM.	String

Fields

Description

Data type

index

Option number

Integer

type

Configuration type. Must be flow

String

flowId

Flow ID

Integer

tittle

Option text. The text must be the same as the one in the HSM.

String

{
  "actions": {
    "setState": {
      "type": "options",
      "options": [
        {
          "index": 1,
          "type": "flow",
          "flowId": 1111,
          "title": "Tittle 1"
        },
        {
          "index": 2,
          "type": "flow",
          "flowId": 2222,
          "title": "Tittle 2"
        }
      ],
      "ttl": 86400
    }
  }
}

3. Cache Parameters

This feature is used to save extra information in the cache to utilize it further. It will depend on the desired configuration for the HSM. If you send a URL, it can be used by a flow to redirect that URL for marketing purposes. All parameters to be cached must go in setStoreParams with their respective key-value fields.

This configuration will be valid for 3 months.

{
  "actions": {
    "setStoreParams": {
      "url": "https://apps.jelou.ai"
    }
  }
}

Request details

Key

Type

Description

destinations

Array[String]

Contains the phone numbers where the message will be sent, phone numbers must contain the country code and must not contain special characters such as "+" or "(".

parameters

Array[String]

Values that will replace the parameters defined on HSM, these must be send in the specific order in which they want to be replaced.

elementName

String

HSM unique name for your company.

bot

String

Bot Id that will send the message.

type

String

The field refers to the types of notifications that are supported and can be text, image, video, document, button and location.

sub_type

String

Optional field. If the type is "button" then sub_type is needed. There are two subtypes, "quick_reply" and "url".

buttonPayloads

Array[Object]

Optional field. This field contains an array of objects. There can be only up to three objects. Every object has two keys, "flowId" refers to the flow that the button must follow, "action" refers to the name of the button.

Response detail

Key

Type

Description

id

String

id of the message. Thisid will allow you to know the status of the message in the future.

destination

String

Destination number.

Sample API request

Test message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1",
		"PARAMETER_2"
	],
	"type": "hsm",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Image message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [],
	"mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images/sample.jpeg",
	"type": "image",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Document message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1"
	],
	"mediaUrl":"https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images/PDF_test.pdf",
	"type": "document",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Video message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [],
	"mediaUrl":"https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images/SampleVideo_1280x720_1mb.mp4",
	"type": "video",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Text with quick reply buttons message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1"
	],
	
	"type": "hsm",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Text with call-to-action buttons and dynamic URL message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Accept-Language: es' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"destinations": [
		"593XXXXXXXX"
	],
	"parameters": [
		"PARAMETER_1"
	],
	"dynamicUrlParameter": [
		"URL_PARAMETER"
	],
	"elementName": "ELEMENT_NAME"
}'

Text with call-to-action buttons and static URL message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1"
	],
	"type": "hsm",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Content restrictions for the Authentication category

URLs, media, and emojis are not allowed for authentication template content or parameters.
The parameter length is restricted to a maximum of 15 characters.

PreviousTemplates NextSend Bulk

Last updated 2 hours ago

Send a message

Request Body

Button Payload

Actions payload

1. Configuration to a specific flow

2. Setting up an option menu

3. Cache Parameters

Request details

Response detail

Sample API request

Test message

Content restrictions for the Authentication category