# Tamplates
# Overview
Templates are WhatsApp Business Account assets that can be sent in template messages. Template messages are the only type of message that can be sent to WhatsApp users outside of a customer service window, so templates are commonly used when messaging users in bulk, or when you need to message a user, but no customer service window is open between you and the user.
# Names
Every template must have a name, but names are not unique. This flexibility allows you to create multiple templates with the same name, but in different languages. Template names are limited to a maximum of 512 characters.
# Components
Templates are made up of various text, media, and interactive UI components, which you define upon template creation.
# Parameters
Some template components allow you to define strings that contain one or more parameters. These are replaced with values included by you in your send message payload when you send the template. parameters must be ordered array index numbers, starting from 1, wrapped in double curly brackets: (1...2...and so on). Example values in template creation payloads and real values in template send payloads must appear in the order in which their corresponding placeholders appear in the component text string.
# Media
Template header components can display media assets. If you are creating a template with a media header, you must include example asset in your template creation request.The example asset will be reviewed as part of template review.
# Template status
Templates must have a status of APPROVED before they can be sent in template messages. A template’s status is initially set by the template review process, but can be changed to another value based on usage and quality feedback. Template status changes are communicated via webhooks, but you can use the GET /get-phone-templates endpoint and request the status field to get the status of a template at any time.
# Messaging Limits
Messaging limits are the maximum number of unique WhatsApp user phone numbers your business can deliver messages to, outside of a customer service window, within a moving 24-hour period. Messaging limits are calculated and set at the business portfolio level and are shared by all business phone numbers within a portfolio. This means that if a business portfolio has multiple business phone numbers, it’s possible for one number to consume all of the portfolio’s messaging capability within a given period. Newly created business portfolios have a messaging limit of 250, but this limit can be increased to: 2,000 -> 10,000 -> 100,000 -> 1,000,000
pay attention
Currently you can create a new template only via our website.
# Get Templates
# Endpoint
GET https://019sms.co.il/whatsapp-api/get-phone-templates/:phone/:templateId?
# Header
| Name | Type | Required |
|---|---|---|
| Authorization | Bearer authentication | ✔️ |
| Content-Type | application/json | ✔️ |
# Request parameters
| Name | Type | Description | Required |
|---|---|---|---|
| phone | string | Your WhatsApp number. international number without +. for example: 972771234567 | ✔️ |
| templateId | string | The specific template ID for which you would like to receive data. | ➖ |
# Response example
json
Copy code
# Response parameters
| Name | Type | Description | Options |
|---|---|---|---|
| success | boolean | The status of request | true/false |
| templates | array of objects | Array of object that contains information about your templates | |
| templates -> name | string | The template name | |
| templates -> templateId | string | The template id to use when you want to send this template | |
| templates -> headerSample | string | The link to sample of media | |
| templates -> body | string | The body message | |
| templates -> footer | string | The footer message | |
| templates -> buttons | string | Buttons types in the template | 1 - No buttons 2 - for "call to action" only 3 - for "quick reply" only 4 - both call to action and quick reply combination |
| templates -> callToAction | string | setup the call to action | 1 - One website button only 2 - Call button only 3 - One website + Call button |
| templates -> callToActionWebsiteText | string | The website text to show | |
| templates -> callToActionWebsiteType | string | website link type | 1 - for static URL (meaning, no variable) 2 - for dynamic with one variable automatically added at the end of the URL |
| templates -> callToActionWebsiteURL | string | Website link URL | |
| templates -> callToActionCallText | string | The button text for the call | |
| templates -> callToActionCallNumber | string | The number to dial, with country code and + | |
| templates -> quickReply 1-3 | string | The quick reply buttons. | |
| templates -> headers | string | The media type chose to be sent as part of the template | 1 - no media 2 - image 3 - video 4 - document |
| templates -> status | string | The status of the template | 0 - send for approval 1 - approved 2 - Template rejected. reason: wrong format template / too many variables / template is similar to other template already exist in your account. 3 - Template rejected. reason: The template contains content that is violating WhatsApp policy. 4 -Template rejected. reason: The template contains content that is marked as Spam. 5 - Template rejected. reason unknown. 6 - Template received too many spam reports. you cant use this template for the next 6 hours. 7 - Template is banned to use due to too many spam reports. 9 - The template has been deleted from meta. 10 - The template is flagged, it received high amount of negative reports from users. be careful!. 11 - The template is no longer flagged. |
# Send a template
# Remarks
- If you send a template message to the client, and the client did not reply yet, and you want to send another message to him, you must use the template message again.
- The billing is per "conversation". conversation means a 24 hours session between you and the client (this 24 hours conversation session is unrelated to the 24 hours timer for template message).
- 24 hours session conversation starts when you send a message to the client.
- Every time the user replies, the template message session resets. which means that you don't have to use template message during this 24 hours template message session.
- If your template has variables, you must provide all variables data (inside bodyVariable parameter).
- The entire template body + variables should not exceed 1024 characters.
- You can send up to 2 template message without getting any response,afterwards you will get an error.
# Endpoint
POST https://019sms.co.il/whatsapp-api/send-whatsapp-template
# Header
| Name | Type | Required |
|---|---|---|
| Authorization | Bearer authentication | ✔️ |
| Content-Type | application/json | ✔️ |
# Request parameters
| Name | Type | Description | Required |
|---|---|---|---|
| source | string | Your WhatsApp account. international number without +. for example: 972771234567 | ✔️ |
| destination | string | The number you want to send the message to. for example: 972501234567 | ✔️ |
| templateId | string | The template id you want to send | ✔️ |
| dynamicFieldsObject | string | In case you used variables 1 to 5 with your body when submitting the template, this is where you provide them. Each item as a variable (1 to 5), not array. Two important rules: 1. you can not use \n new line inside a variable. 2. you can not use 4 or more consecutive spaces inside a variable | ➖ |
| couponCode | string | in case you used coupon code in the template, here you put the code. 15 digits maximum. | ➖ |
| couponExpiration | string | in case you used coupon code in the template, and set 'true' for code expiration, here you put the expiration date for example: "13/05/2025 12:02" | ➖ |
| headerLink | string | In case you used image/video/document header, this is the link for image or video or document limitation: image (png, jpg, gif, jpeg) - 5 MB document (pdf,doc,docx,xls,xlsx,ppt,ppts,zip,txt,rar) - 100 MB video (mp4, avi, 3gpp) - 16 MB | ➖ |
| websiteVariable | string | in case you used call to action button, and you chose dynamic "website" here you should put the dynamic field | ➖ |
| websiteVariable2 | string | in case you used second website for call to action button, and you used dynamic variable here you should put the dynamic field | ➖ |
| otp | string | If your template is authentication template, here is where you provide the code maximum 15 characters(can be a combination of numbers, letters, special characters etc) | ➖ |
# Request example
json
Copy code
# Authentication request example
json
Copy code
# Response example
json
Copy code
# Response parameters
| Name | Type | Description | Options |
|---|---|---|---|
| success | boolean | The status of request. | true/false |
| ans -> status | string | Status of sending the message | OK / FAIL |
| ans -> unique | string | Unique ID for any message | |
| ans -> body | string | The text you sent | |
| ans -> timestamp | timestamp | Time stamp | |
| ans -> from | string | Your WhatsApp account | |
| ans -> to | string | The number that the message was sent to | |
| ans -> templateTimeLeft | number | Amount of minutes left since client's last message. if passed, you must use Template Message. This value resets every time the client is sending you a message. | |
| ans -> reason | string | The status explanation in case of FAIL | see the table below |
# Reason explanation
| Reason | Description |
|---|---|
| 1 | Not FAIL. the status is OK |
| 2 | Your "from" number account does not exist, or JSON syntax error |
| 3 | General error |
| 4 | 'to' is either empty or wrong number format or WhatsApp number does not exist |
| 6 | WhatsApp error or template rejected |
| 12 | Problem with the template name, or variables structure, please check the variables and the structure of the template |
| 13 | Language is empty, invalid or does not fit the language of the template when created |
| 14 | headerType is empty, invalid or does not fit the header of the template when created. moreover, body / header variables can not have new lines \n |
| 15 | You must provide headerVariable for this template, without special characters such as ** |
| 17 | bodyVariable must be equal to the number of variables used when creating the template, and must not be empty. |
| 18 | You must provide websiteVariable for this template |
| 19 | The template you created is too long (more than 1024), create another one |
| 20 | The template needs a coupon code / expiration time or the coupon code / expiration time is too long or invalid |
| 21 | WhatsApp has rejected the sending of the template due to high volume sending. please try to send again. |
| 22 | Rate limit error, try again |
# Send template campaign
when to use?
You should use the "Send template campaign" API in the following scenarios:
- Sending template messages to multiple destinations in bulk.
- Delivering template messages to a predefined contact list.
- Scheduling a future campaign with specific timing.
# Remarks
- You can only send template messages to private people, not groups.
- If you send a template message to the client, and the client did not reply yet, and you want to send another message to him, you must use the template message again.
- The billing is per "conversation". conversation means a 24 hours session between you and the client (this 24 hours conversation session is unrelated to the 24 hours timer for template message).
- You can send unlimited template messages within the 24 hours session time of a conversation.
- 24 hours session conversation starts when you send a message to the client.
- Every time the user replies, the template message session resets. which means that you don't have to use template message during this 24 hours template message session.
- If your template has variables, you must provide all variables data (inside bodyVariable parameter).
- The entire template body + variables should not exceed 1024 characters.
# Endpoint
POST https://019sms.co.il/whatsapp-api/create-campaign-wa
# Header
| Name | Type | Required |
|---|---|---|
| Authorization | Bearer authentication | ✔️ |
| Content-Type | application/json | ✔️ |
# Request parameters
| Name | Type | Description | Required |
|---|---|---|---|
| source | string | Your WhatsApp account. international number without +. for example: 972771234567 | ✔️ |
| destinations | object | The destinations object whis optional keys [phones,cl] | ✔️ |
| destinations -> phones | array of strings | Array of strings represents phone numbers. for example : :["972552222222","972553333333"] | |
| destinations -> cl | array of strings | Array of strings represents contact list id. for example : :["762524","762525"] | |
| campaign_message | string | The template id you want to send | ✔️ |
| campaign_name | string | A name for the campaign | ➖ |
| dynamicHeaders | object | In case you used variables 1 to 5 with your body when submitting the template, this is where you provide them. Each item as a dynamic field from your contact list. you can use the original colmn name or just use "df1"," df2" etc. | ➖ |
| dynamicHeaders -> 1-5 | string | The dynamic field from your contact list to replace with. you can use "df1"," df2" etc. | |
| header_link | string | In case you used image/video/document header, this is the link for image or video or document | ➖ |
| future_campaign | string | In case you want to add timing, put the value "future" otherwise "instant" | ✔️ |
| from_date | string | In case you want to add timing, put the date here in this format "05/01/2025 14:30" | ➖ |
| couponCode | string | in case you used coupon code in the template, here you put the code. 15 digits maximum. you can use dynamic field, example for field dynamic 4 put "couponCode":"4", | ➖ |
| couponExpiration | string | in case you used coupon code in the template, and set 'true' for code expiration, here you put the expiration date for example: "13/05/2025 12:02" | ➖ |
| couponType | string | in case you used coupon code in the template, here you put the coupon type, 1 for permennent code 2 for dynamic code. | |
| websiteVariable | string | in case you used call to action button, and you chose dynamic "website" here you should put the dynamic field, example for field dynamic 4 put "websiteVariable" :4 | ➖ |
| websiteVariable2 | string | in case you used second website for call to action button, and you used dynamic variable here you should put the dynamic field, example for field dynamic 4 put "websiteVariable" :4 | ➖ |
# Request example
json
Copy code
# Response example
json
Copy code
# Response parameters
| Name | Type | Description | Options |
|---|---|---|---|
| success | boolean | The status of request. | true/false |
| sum | number | The total amount of destinations numbers received,also the estimations of credits cost |