Templates

HSMs can be personalized by inserting content into a template, such as the recipient's name or specific order details. These placeholders are replaced with actual data when the message is sent.

Once you understand how the structure works and before creating a new template you have to be sure about which templates are already set in your bot. You can check it first by choosing Get Templates. Subsequently, you can create a new one by using the Create Template subsection.

Remember "Templates" are the skeleton of your message and they are approved or rejected by the WhatsApp crew, so it is essential to follow the guidelines to create a proper layout.

Get Templates

GET https://api.jelou.ai/v1/bots/:botId/templates

Returns all templates for your bot.

Path Parameters

Name	Type	Description
botId	string	Describe your bot id required for search your templates

Name

Type

Description

botId

string

Describe your bot id required for search your templates

Query Parameters

Name	Type	Description
query	String	Search template by elementName
status	String	Search templates by status. Possible values: PENDING, REJECTED, APPROVED
category	String	Search templates by category. Possible values: UTILITY, MARKETING, AUTHENTICATION

Name

Type

Description

query

String

Search template by elementName

status

String

Search templates by status. Possible values: PENDING, REJECTED, APPROVED

Create Template

POST https://api.jelou.ai/v1/bots/:botId/templates

Create an HSM Template.

Path Parameters

Name	Type	Description
botId*	string	Bot id

Name

Type

Description

botId*

string

Bot id

Query Parameters

Name	Type	Description
sendToAprove	boolean	Defines if a template should be sent to WhatsApp for approval

Name

Type

Description

sendToAprove

boolean

Defines if a template should be sent to WhatsApp for approval

Request Body

Name Type Description

Name	Type	Description
category*	string	The category of HSM template Values: `UTILITY`, `MARKETING`, `AUTHENTICATION`
language*	string	Template language.
isVisible	boolean	Defines if the templare should be shown to operators
params*	object	Parameter structure. For the Authentication category, Meta has restricted to one parameter.
paramsNumber*	number	Number of parameters. For the Authentication category, Meta has restricted to one parameter.
elementName*	string	Unique template identifier. It can only contain uppercase letters, underscore (_), and numbers.
displayName*	string	Template display name
template*	string	Template body. For the Authentication category, Meta has restricted the content. Review the restrictions for this category.
type*	string	HSM type. Values: `HSM`, `IMAGE`, `VIDEO`, `DOCUMENT`
mediaUrl	string	String of the URL media. Required when the HSM type is `IMAGE`, `VIDEO`, `DOCUMENT.`Not applicable for Authentication category
interactiveAction*	string	Interactive action of the HSM. Values: `NONE`, `CALL_TO_ACTION`, `QUICK_REPLY, OTP`
buttons	array	Button structure. Required when the interactive action of the HSM is `CALL_TO_ACTION ,` `QUICK_REPLY or OTP`
header	string	Template header. Applicable only for Text type templates. Not applicable for Authentication category and has a limit of 60 characters.
exampleHeader	string	Example of the header. Mandatory only if the template will have a header.
headerParams	String	Parameter structure. The header supports a maximum of one parameter.
example*	string	Example of the template. If the template has a parameter, the parameter should be replaced with an example.
extraSettings	Object	Optional settings for the template. Read the structure section for more information

category*

string

The category of HSM template Values: UTILITY, MARKETING, AUTHENTICATION

language*

string

Template language.

isVisible

boolean

Defines if the templare should be shown to operators

params*

object

Parameter structure. For the Authentication category, Meta has restricted to one parameter.

paramsNumber*

number

Number of parameters. For the Authentication category, Meta has restricted to one parameter.

elementName*

string

Unique template identifier. It can only contain uppercase letters, underscore (_), and numbers.

displayName*

string

Template display name

template*

string

Template body. For the Authentication category, Meta has restricted the content. Review the restrictions for this category.

type*

string

HSM type. Values: HSM, IMAGE, VIDEO, DOCUMENT

mediaUrl

string

String of the URL media. Required when the HSM type is IMAGE, VIDEO, DOCUMENT.Not applicable for Authentication category

interactiveAction*

string

Interactive action of the HSM. Values: NONE, CALL_TO_ACTION, QUICK_REPLY, OTP

buttons

array

Button structure. Required when the interactive action of the HSM is CALL_TO_ACTION , QUICK_REPLY or OTP

header

string

Template header. Applicable only for Text type templates. Not applicable for Authentication category and has a limit of 60 characters.

exampleHeader

string

Example of the header. Mandatory only if the template will have a header.

headerParams

String

Parameter structure. The header supports a maximum of one parameter.

example*

string

Example of the template. If the template has a parameter, the parameter should be replaced with an example.

extraSettings

Object

Optional settings for the template. Read the structure section for more information

{
  "message": [
    "Template has been created."
  ],
  "status": "success",
  "data": {
    "template": "¡Hola! Somos *Jelou*. \nTe damos la bienvenida _{{1}}_. Pronto {{2}} del equipo de desarrollo se comunicará contigo.",
    "displayName": "Bienvenida Desarrollo",
    "elementName": "test_hsm_api",
    "params": [
      {
        "label": "Nombre del cliente",
        "param": "1"
      },
      {
        "label": "Nombre del desarrollador",
        "param": "2"
      }
    ],
    "paramsNumber": 2,
    "isVisible": false,
    "language": "ES",
    "createdAt": "2021-01-28T15:08:38.492Z",
    "updatedAt": "2021-01-28T15:08:38.492Z",
    "botId": "<botId>",
    "companyId": 5,
    "status": "APPROVED"
  }
}

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

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

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

The status field defines whether or not your template was approved by Whatsapp.

Language

The supported language by WhatsApp is detailed on the official page, please check it carefully on the following link.

Content Restrictions (Authentication category)

Meta has restricted the content for the authentication category, the content will be according to the language of the template. Meta is restricted to one parameter.

Language	Language code	Content
English	en	{{1}} is your verification code.
Portuguese (BR)	pt_BR	Seu código de verificação é {{1}}.
Spanish	es	Tu código de verificación es {{1}}.

Language

Language code

Content

English

{{1}} is your verification code.

Portuguese (BR)

pt_BR

Seu código de verificação é {{1}}.

Spanish

Tu código de verificación es {{1}}.

Params Structure

Use the following structure in the params field when creating a template:

[
    {
        "label": "Nombre del cliente",
        "param": "1"
    },
    {
        "label": "Nombre del desarrollador",
        "param": "2"
    }
]

Button Structure

Use the following structure in the buttonsfield when the interactive actions are CALL_TO_ACTION ,QUICK_REPLY or OTP

1. QUICK_REPLY

It is used to get quick replies so a user can give a reply when a message shows up by pushing a button easily. It is an array of objects and it can have a maximum of 3 buttons. Each object has two fields.

Field Description

Field	Description
text	Button text, this value cannot be updated.
type	Button type. Value `QUICK_REPLY`

text

Button text, this value cannot be updated.

type

Button type. Value QUICK_REPLY

[
  {
    "text": "Más información",
    "type": "QUICK_REPLY"
  },
  {
    "text": "Hablar con operador",
    "type": "QUICK_REPLY"
  },
  {
    "text": "Ventas",
    "type": "QUICK_REPLY"
  }
]

2. CALL_TO_ACTION

It is used to offer a call-to-action so a user can take an action based on their shown options. It is an array of objects. It can have a maximum of 2 buttons and a maximum of 1 button of each type.

Field Description

Field	Description
text	Button text, this value cannot be updated.
type	Button type. Value `PHONE_NUMBER`, `URL`
phone_number	Phone number of the button.
url	URL of the button.
example	Example of the URL. Required when the button type is URL.

text

Button text, this value cannot be updated.

type

Button type. Value PHONE_NUMBER, URL

phone_number

Phone number of the button.

url

URL of the button.

example

Example of the URL. Required when the button type is URL.

[
  {
    "text": "Ventas",
    "phone_number": "+5939123456789",
    "type": "PHONE_NUMBER"
  },
  {
    "type": "URL",
    "text": "Jelou Apps",
    "url": "https://apps.jelou.ai/{{1}}",
    "example": "https://apps.jelou.ai/bots"
  }
]

3. OTP

It is used to get a "One Time Password". It is an array of objects. It can have a maximum of 1 button.

Field Description

Field	Description
text	Button text, this value cannot be updated.
type	Button type. Value `OTP`

text

Button text, this value cannot be updated.

type

Button type. Value OTP

[
  {
    "text": "COPY CODE",
    "type": "OTP"
  }
]

extraSettings Structure

Field	Type	Description
addSecurityRecommendation	Boolean	Adds an additional security message in Authentication templates.
codeExpirationMinutes	Number	Adds a footer message with the code expiration time. Values between 1-90 minutes.
allowChangeCategory	Boolean	Let Meta to update the template category if it is required.

Field

Type

Description

addSecurityRecommendation

Boolean

Adds an additional security message in Authentication templates.

codeExpirationMinutes

Number

Adds a footer message with the code expiration time. Values between 1-90 minutes.

allowChangeCategory

Boolean

Let Meta to update the template category if it is required.

Sample API request

1. Text

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: application/json' \
  --data '{
	"displayName": "template text utility",
	"template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please contact support. Thank you for being a customer!",
	"example": "Thank you for your order, Omar! Your confirmation number is 71936. If you have any questions, please contact support. Thank you for being a customer!",
	"elementName": "template_text_utility",
	"params": [
		{
			"param": "1",
			"label": "client",
			"example": "Omar"
		},
		{
			"param": "2",
			"label": "order",
			"example": "71936"
		}
	],
	"paramsNumber": "2",
	"type": "HSM",
	"language": "es",
	"category": "UTILITY",
	"interactiveAction": "NONE"
}'

2. Text with quick reply buttons

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: application/json' \
  --data '{
	"displayName": "template quick reply",
	"template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
	"example": "Thank you for your order, Omar! Your confirmation number is 57893. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
	"elementName": "template_quick_reply",
	"params": [
		{
			"param": "1",
			"label": "client",
			"example": "Omar"
		},
		{
			"param": "2",
			"label": "order",
			"example": "57893"
		}
	],
	"paramsNumber": "2",
	"type": "HSM",
	"language": "en",
	"category": "UTILITY",
	"interactiveAction": "QUICK_REPLY",
	"buttons": [
		{
			"text": "Contact Support",
			"type": "QUICK_REPLY"
		},
		{
			"text": "Contact Sales",
			"type": "QUICK_REPLY"
		}
	]
}'

3. Text with call-to-action buttons

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: application/json' \
  --data '{
	"displayName": "template_call_action",
	"template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
	"example": "Thank you for your order, Omar! Your confirmation number is 67996. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
	"elementName": "template_call_action",
	"params": [
		{
			"param": "1",
			"label": "client",
			"example": "Omar"
		},
		{
			"param": "2",
			"label": "order",
			"example": "67996"
		}
	],
	"paramsNumber": "2",
	"type": "HSM",
	"language": "en",
	"category": "UTILITY",
	"interactiveAction": "CALL_TO_ACTION",
	"buttons": [
		{
			"text": "Contact Support",
			"type": "URL",
			"url": "https://apps.jelou.ai",
			"example": "https://apps.jelou.ai"
		},
		{
			"text": "Call",
			"type": "PHONE_NUMBER",
			"phone_number": "+15552051314"
		}
	]
}'

4. Image

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: application/json' \
  --data '{
	"displayName": "template_sample_image",
	"template": "Hi {{1}}. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai",
	"example": "Hi Omar. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai",
	"elementName": "template_sample_image",
	"params": [
		{
			"param": "1",
			"label": "client",
			"example": "Omar"
		}
	],
	"paramsNumber": "1",
	"type": "IMAGE",
	"language": "en",
	"category": "MARKETING",
	"mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images%2Fjeloupocket.jpeg",
	"interactiveAction": "NONE"
}'

5. Document

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: application/json' \
  --data '{
	"displayName": "test_document_",
	"template": "Hi {{1}}. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai",
	"example": "Hi Omar. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai",
	"elementName": "test_document_",
	"params": [
		{
			"param": "1",
			"label": "client",
			"example": "Omar"
		}
	],
	"paramsNumber": "1",
	"type": "DOCUMENT",
	"language": "en",
	"category": "MARKETING",
	"mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images%2FdocuementTest.pdf",
	"interactiveAction": "NONE"
}'

6. Video

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: application/json' \
  --data '{
	"displayName": "test_video_1",
	"template": "Hi {{1}}. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai",
	"example": "Hi Omar. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai",
	"elementName": "test_video_1",
	"params": [
		{
			"param": "1",
			"label": "client",
			"example": "Omar"
		}
	],
	"paramsNumber": "1",
	"type": "VIDEO",
	"language": "en",
	"category": "MARKETING",
	"mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images%2FvideoTest.mp4",
	"interactiveAction": "NONE"
}'

PreviousStructure NextSend

Last updated 2 hours ago