POST

Create Message

Sends an outbound message in a conversation over any supported channel.

POSThttps://api.vantaxai.com/v1/conversations/{conversation_id}/messages

Create a message to reply to a contact on their channel. The `channel` you pass determines which fields are required: • **SMS / WhatsApp** — set `content` and `from_phone_number_id` (the owned number to send from). Optionally attach `media_url` for MMS / media messages. • **Facebook Messenger / Instagram** — set `content`. The connected Page or IG account that owns the conversation is used automatically; `media_url` may carry images. • **Email** — set `content` plus a `subject`. You may also pass `html` for a rich-text body; `content` is used as the plain-text fallback. The message is sent immediately and returns with an initial `status` of `queued` or `sent`; delivery state is updated asynchronously to `delivered` or `failed`.

Channel-specific requirements

SMS and WhatsApp require `from_phone_number_id`. Email requires `subject`. Facebook Messenger and Instagram route through the connected Page / IG account that owns the conversation — no extra fields needed.

Messaging windows

Facebook Messenger, Instagram, and WhatsApp enforce platform-side messaging windows (e.g. WhatsApp's 24-hour customer service window). Sending outside the window may be rejected with a 422 — use an approved template instead.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…
Content-Typestringrequired
Must be application/json for requests with a body.
example: application/json

Path Parameters

conversation_idstringrequired
The conversation to post the message into.
example: conv_4b8e21

Body Parameters

channelstringrequired
The channel to send on. Must match a channel the contact can be reached on.
smswhatsappfacebookinstagramemail
example: sms
contentstringrequired
The message body (max 4000 chars). For email, this is the plain-text body / fallback.
example: Yes! We're open Saturday 9am–4pm.
subjectstringoptional
Email subject line (max 255 chars). Required when channel is `email`, ignored otherwise.
example: Re: Saturday hours
htmlstringoptional
Optional rich-text HTML body for email. When omitted, `content` is sent as plain text.
example: <p>Yes! We're open <b>Saturday 9am–4pm</b>.</p>
from_phone_number_idstringoptional
Owned phone number to send from. Required for `sms` and `whatsapp` channels.
example: pn_55ad12
media_urlarrayoptional
Optional list of publicly accessible media URLs to attach (MMS / images). Ignored by `email`.
example: ["https://cdn.example.com/menu.jpg"]

Request

# Channel: SMS — requires from_phone_number_id, optional media_url for MMS
curl -X POST https://api.vantaxai.com/v1/conversations/conv_4b8e21/messages \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "content": "Yes! We are open Saturday 9am-4pm. Want me to book a slot?",
    "from_phone_number_id": "pn_55ad12"
  }'

# Channel: WhatsApp — requires from_phone_number_id, media_url optional
curl -X POST https://api.vantaxai.com/v1/conversations/conv_4b8e21/messages \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "content": "Here is the menu you asked about 🍽",
    "from_phone_number_id": "pn_55ad12",
    "media_url": ["https://cdn.example.com/menu.jpg"]
  }'

# Channel: Facebook Messenger — uses the connected Page automatically
curl -X POST https://api.vantaxai.com/v1/conversations/conv_4b8e21/messages \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "facebook",
    "content": "Thanks for reaching out! How can we help today?"
  }'

# Channel: Instagram — uses the connected IG account, media_url optional
curl -X POST https://api.vantaxai.com/v1/conversations/conv_4b8e21/messages \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "instagram",
    "content": "Loved your comment! Here is a closer look.",
    "media_url": ["https://cdn.example.com/product-closeup.jpg"]
  }'

# Channel: Email — requires subject, optional html rich-text body
curl -X POST https://api.vantaxai.com/v1/conversations/conv_4b8e21/messages \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "subject": "Re: Saturday hours",
    "content": "Yes! We are open Saturday 9am-4pm.",
    "html": "<p>Yes! We are open <b>Saturday 9am-4pm</b>.</p>"
  }'

// Channel: SMS
const res = await fetch(
  "https://api.vantaxai.com/v1/conversations/conv_4b8e21/messages",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer vx_live_3fa9c2...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      channel: "sms",
      content: "Yes! We are open Saturday 9am-4pm.",
      from_phone_number_id: "pn_55ad12",
    }),
  }
);
const { data: message } = await res.json();

// Channel: SMS
const message = await vantax.messages.create({
  conversationId: "conv_4b8e21",
  channel: "sms",
  content: "Yes! We are open Saturday 9am-4pm.",
  fromPhoneNumberId: "pn_55ad12",
});

# Channel: SMS
message = vantax.messages.create(
    conversation_id="conv_4b8e21",
    channel="sms",
    content="Yes! We are open Saturday 9am-4pm.",
    from_phone_number_id="pn_55ad12",
)

Response

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "id": "msg_7c1a4f",
    "conversation_id": "conv_4b8e21",
    "channel": "sms",
    "direction": "outbound",
    "content": "Yes! We are open Saturday 9am-4pm. Want me to book a slot?",
    "subject": null,
    "sender_type": "human",
    "media_url": [],
    "status": "sent",
    "created_at": "2026-01-14T10:30:12Z"
  }
}

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "id": "msg_8d2b71",
    "conversation_id": "conv_4b8e21",
    "channel": "email",
    "direction": "outbound",
    "content": "Yes! We are open Saturday 9am-4pm.",
    "subject": "Re: Saturday hours",
    "sender_type": "human",
    "media_url": [],
    "status": "queued",
    "created_at": "2026-01-14T10:31:05Z"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "from_phone_number_id", "message": "from_phone_number_id is required to send an SMS" }
  ]
}

{
  "success": false,
  "message": "Conversation not found"
}