Carousel Messaging API

Send multiple images as a swipeable carousel in iMessage. Carousel messaging is only available on V2 (Mac Mini) lines.

Send a Carousel

POST https://api.sendblue.co/api/send-carousel

Request Body

Parameter	Type	Required	Description
number	string	Yes	Recipient phone number (E.164). Aliases: recipient, to
from_number	string	Yes	Your V2 (Mac Mini) Sendblue line (E.164). Aliases: fromNumber, from, sendblue_number
media_urls	string[]	Yes	Array of 2–20 HTTPS image URLs. Alias: mediaURLs
status_callback	string	No	Webhook URL for delivery status. Alias: statusCallback
send_style	string	No	iMessage send effect. Alias: sendStyle
metadata	object	No	Custom metadata returned in webhooks

Example Request

curl -X POST 'https://api.sendblue.co/api/send-carousel' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+19175551234",
    "from_number": "+14155559876",
    "media_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ]
  }'

Node.js Example

const axios = require('axios');

await axios.post(
  'https://api.sendblue.co/api/send-carousel',
  {
    number: '+19175551234',
    from_number: '+14155559876',
    media_urls: [
      'https://example.com/image1.jpg',
      'https://example.com/image2.jpg',
      'https://example.com/image3.jpg'
    ]
  },
  {
    headers: {
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
);

Success Response (202)

{
  "status": "QUEUED",
  "accountEmail": "[email protected]",
  "message_handle": "abc123-def456",
  "number": "+19175551234",
  "from_number": "+14155559876",
  "media_url": "https://example.com/image1.jpg",
  "is_outbound": true,
  "message_type": "carousel"
}

---

Error Responses

Missing or invalid media_urls (400)

{
  "status": "ERROR",
  "message": "'media_urls' is required — an array of 2-20 HTTPS URLs"
}

Too few media URLs (400)

{
  "status": "ERROR",
  "message": "Carousel requires at least 2 media URLs. For single media, use /send-message with media_url."
}

Too many media URLs (400)

{
  "status": "ERROR",
  "message": "'media_urls' must contain at most 20 items"
}

Non-HTTPS URL (400)

{
  "status": "ERROR",
  "message": "media_urls[0] must be an HTTPS URL"
}

Missing from_number (400)

{
  "status": "ERROR",
  "message": "You must specify a valid `from_number` in the request body."
}

V2 line required (400)

{
  "status": "ERROR",
  "message": "Carousel messaging is only available on V2 lines"
}

Cannot send to self (400)

{
  "status": "ERROR",
  "message": "Cannot send messages to self"
}

Line not found (404)

{
  "status": "ERROR",
  "message": "The from_number is not registered"
}

Notes

1. V2 Only: Carousel messaging requires a V2 (Mac Mini) Sendblue line. It is not available on V1 lines.

2. 2–20 Images: You must provide between 2 and 20 HTTPS image URLs. For sending a single image, use /api/send-message with the media_url parameter.

3. HTTPS Required: All media URLs must use HTTPS.