Send

Use this feature to send an Outbound message 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. For a visual guide, consult the Send Bulk section

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 an Outbound 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.

200

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"
  }
]

400: Bad Request

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": "[phone]",
      "botName": "Jelou Dev WhatsApp"
    }
  },
  "error": {}
}

404: Not Found

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."
    }
  }
}

422: Unprocessable Entity

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."
      }
    ]
  }
}

500: Internal Server Error

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

Use the following structure in the buttonPayloads field when the template has quick reply buttons:

[
  {
    "flowId": 23838,
    "action": "Mas información"
  },
  {
    "flowId": 24278,
    "action": "Contactar con agencia"
  }
]

There can be only up to three objects. Every object has two keys "flowId" refers to the flow that the button must follow (please contact Jelou team for flowId information), and "action" refers to the name of the button.

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
    }
  }
}

2. Setting up an option menu

Set up a flow for each of the outbound 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

{
  "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

1. Test message

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

2. Image message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
  --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"
}'

3. Document message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
  --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"
}'

4. Video message

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
  --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"
}'

5. Text with quick reply buttons message

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

6. 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 dXNlcjpwYXNzd29yZA==' \
  --header 'Content-Type: application/json' \
  --data '{
	"destinations": [
		"593XXXXXXXX"
	],
	"parameters": [
		"PARAMETER_1"
	],
	"dynamicUrlParameter": [
		"URL_PARAMETER"
	],
	"elementName": "ELEMENT_NAME"
}'

7. 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 dXNlcjpwYXNzd29yZA==' \
  --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.