# 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.
billing
After the first 1,000 messages each month, every additional message is billed at 0.5 credits.
# 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.
- 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 |