# Send List
pay attention
You can use the "Send List" API in one case only:
You reply to a message that the client sent, within 24 hours since the client sent his last message.
If you send a message to a new client, or try to send a message to an old client (old client means that 24 hours since client's last message has passed), you must use the "Send Template Message" API instead.
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.
# Remarks
- You can use the "Send List" API in one case only - for reply to a message that the client sent, within 24 hours since the client sent his last message. If you send a message to a new client, or try to send a message to an old client (old client means that 24 hours since client's last message has passed), you must use the "Send Template Message" API instead. 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.
- You can only send a list to private people, not groups.
- 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 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.
# Endpoint
POST https://019sms.co.il/whatsapp-api/send-list
# 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 | ✔️ |
| header | string | The title of the list box. you can have Emoji. | ➖ |
| message | string | The body text of the list box. Its usually widely used to describe what this list is about. | ✔️ |
| footer | string | Some footer message | ➖ |
| buttonText | string | The text of the button that will appear on the list box. you can use Emoji. | ✔️ |
| itemTitle1-10 | string | List of items, minimum is 1, maximum is 10. | at least 1 item is mandatory |
| itemDescription1-10 | string | Extra description for the item, it will show below the title. | ➖ |
| buttonText | string | The text of the button that will appear on the list box. you can use Emoji. | ✔️ |
| replyTo | string | In case you want to reply to a message that the end user has sent (quoted message), here you can provide the unique ID of that message | ➖ |
# Request example
POST whatsapp-api/send-list HTTPS/1.1
Content-Type: application/json
{
"source": 972555555555,
"destination": 972550000000,
"header": "This is header",
"message": "this is body",
"footer": "Footer goes here",
"buttonText": "Click to open",
"itemTitle1": "Customer service",
"itemDescription1": "Choose me for customer service",
"itemTitle2": "Sales",
"itemDescription2": "Sales enquiries? click here",
"itemTitle3": "Support"
"replyTo": ""
}
# Response example
Content-Type: application/json
{
"success": true,
"ans": {
"status": "OK",
"unique": "HBgMOTcyNTI2ODkzMjQ1FQIAERgSRdDU4RjIyQjY2MEI5NUVEMUM4AA==",
"header": "your header",
"body": "your body",
"footer": "your footer",
"timestamp": 1600115719,
"from": "972507654321",
"to": "972501234567",
"templateTimeLeft": 0,
"conversationTimeLeft": 0,
"reason": 1
}
}
# Response parameters
| Name | Type | Description | Options |
|---|---|---|---|
| success | boolean | The status of request. | true/false |
| ans | object | The response object | |
| ans -> status | string | Status of sending the message | OK / FAIL |
| ans -> unique | string | Unique ID for any message | |
| ans -> header | string | the text you send | |
| ans -> body | string | The number that the message was sent to | |
| ans -> footer | string | footer text | |
| 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 -> conversationTimeLeft | number | Amount of minutes left for the conversation session to end. if passed, any message after that, will be considered as a new conversation, and the timer will reset. | |
| 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 |
| 5 | 'body' can't be empty |
| 6 | WhatsApp error |
| 7 | You are trying to send a message but it has been more than 24 hours since client's last message. please use 'Send Template' instead |
| 8 | You are trying to send a message for first time to a contact. please use 'Send Template' message instead |
| 9 | header is too long |
| 10 | footer is too long |
| 11 | buttonText is mandatory and must be less than 20 characters |
| 12 | itemTitle1 is mandatory, and less than 24 characters |
| 13 | one (or more) of your itemTitle is more than 24 characters |
| 14 | one (or more) of your itemDescription is more than 72 characters |
| 15 | rate limit error |