# Send Carousel
pay attention
You can use the "Send Carousel" 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 Carousel" 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 carousel 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.
- Message must include between 2 and 10 cards.
- header and footer are not supported.
- cards must include either an image or a video.
- A card must include either a URL/phone/email button or (one/two reply buttons).
- All cards must look the same regarding the buttons type (either 1 with buttonExternal or 2/3 with button1/button2)
- All cards must look the same regarding the card body. if you choose to use a body, all cards must have a body.
- All cards must have the same headerLink type, either an image or a video.
- Make sure you follow the cards numbering right. do not send card5 data without sending card1, card2, card3 and card4 too.
# Endpoint
POST https://019sms.co.il/whatsapp-api/send-carousel
# 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 | ✔️ |
| message | string | The body text that comes with all the cards. max 1024 characters. | ✔️ |
| buttons | number | How the buttons of all cards will be: 1 - buttonExternal type. 2 - one reply button. 3 - two reply buttons. | ✔️ |
| cardX_headerLink | string | Header media URL for card X (X = 1 to 10). Image or video. max 2000 characters. Image up to 5 MB, video up to 16 MB. | min 2 cards, max 10 |
| cardX_body | string | Body text of a card. max 160 characters and up to 2 new lines. | ➖ |
| cardX_buttonExternal | string | External button value when buttons is 1: phone number, https URL, or email. max 1000 characters. | only if buttons is 1 |
| cardX_buttonExternalText | string | Text for the external button. max 20 characters. | only if buttons is 1 |
| cardX_button1 | string | First reply button text when buttons is 2 or 3. max 20 characters. | only if buttons is 2 or 3 |
| cardX_button1ID | string | Optional ID returned in the webhook for button1. default is 1. max 200 characters. | ➖ |
| cardX_button2 | string | Second reply button text when buttons is 3. max 20 characters. | only if buttons is 3 |
| cardX_button2ID | string | Optional ID returned in the webhook for button2. default is 2. max 200 characters. | ➖ |
| 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 | ➖ |
| showRequest | number | Return the original request in the response (without apiKey). 0 off, 1 on. | ➖ |
# Request example
json
Copy code
POST whatsapp-api/send-carousel HTTPS/1.1
Content-Type: application/json
{
"source": 972555555555,
"destination": 972550000000,
"message": "hello, please choose a product you like!",
"buttons": 1,
"card1_headerLink": "https://my-image.com/image.png",
"card1_buttonExternal": "972501234567",
"card1_buttonExternalText": "Call us",
"card2_headerLink": "https://my-image.com/imagetwo.png",
"card2_buttonExternal": "https://google.com",
"card2_buttonExternalText": "Our website"
}
# Response example
json
Copy code
Content-Type: application/json
{
"success": true,
"ans": {
"status": "OK",
"unique": "HBgMOTcyNTI2ODkzMjQ1FQIAERgSRdDU4RjIyQjY2MEI5NUVEMUM4AA==",
"body": "hello, please choose a product you like!",
"timestamp": 1771932645,
"from": "972555555555",
"to": "972550000000",
"templateTimeLeft": 0,
"conversationTimeLeft": 0,
"reason": 1,
"card1_headerLink": "https://my-image.com/image.png",
"card2_headerLink": "https://my-image.com/imagetwo.png"
}
}
# 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 -> 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 -> 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 -> cardX_headerLink | string | The link you provided for any of the cards | |
| ans -> cardX_body | string | The body text you provided for any of the cards (if provided) | |
| 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 | rate limit error |
| 10 | Cards are not in the right format order, or card1 and card2 do not exist |
| 11 | buttons is incorrect or wrong |
| 12 | cardX_headerLink is incorrect or wrong for one or more of the cards |
| 13 | cardX_body is too long or incorrect for one or more of the cards |
| 14 | cardX_buttonExternal is required for the selected buttons type, or is in the wrong format |
| 15 | cardX_buttonExternalText is required since cardX_buttonExternal is in use, or is in the wrong format |
| 16 | cardX_button1 is required for the selected buttons type, or is in the wrong format |
| 17 | cardX_button1ID is wrong or not in the correct format |
| 18 | cardX_button2 is required for the selected buttons type, or is in the wrong format |
| 19 | cardX_button2ID is wrong or not in the correct format |