Messaging guide
Reply to customers by SMS from your help desk or app, with idempotent sends, the reply window, opt-outs, pause and rate limits.
The messaging API lets your help desk or app read a brand's SMS conversations and reply to customers in them. A reply goes out through the same path as a reply from the brand's agents, so it shows in the VYG conversation list. Delivery results and customer texts come back to you as webhooks.
The API replies in existing conversations only. It never starts a conversation, and it cannot text a contact who has never texted the brand.
A typical integration:
- Create an API key with the scopes below.
- Create the brand's webhook endpoint for
message.receivedand the delivery events. - When a customer texts in,
message.receivedarrives with the conversation id. Open a ticket. - Pause the conversation so the brand's agents and automated replies stay out while your team handles it.
- Reply with
POST /v1/conversations/{id}/messages.message.sent, thenmessage.deliveredormessage.failed, report the result. - Resume the conversation when the ticket closes.
Turn it on
The messaging API is in beta. VYG turns it on per brand (the beta:messaging-api permission). Until then every
messaging and webhook endpoint answers 403 with the code feature_not_enabled.
There are no test keys and no test mode: every key acts on the brand's real customers. To build and test an integration, use a key from a separate sandbox brand that has the messaging API turned on, not from your live brand.
Authenticate
Send an API key as a bearer token on every request:
Authorization: Bearer <your API key>A brand admin creates keys in Settings → API keys. A key belongs to one brand and carries only the scopes chosen when it was created. Keep keys on your server; never put one in browser or mobile code. See API keys.
Scopes
| Scope | Allows |
|---|---|
conversations:read | List conversations and read their messages. |
conversations:write | Send replies. |
conversations:pause | Pause and resume conversations, and read their pause state. |
contacts:read | Read contacts. |
contacts:read-phone | Look up a contact's phone number, send by phone number and add phone to webhook payloads. |
webhooks:manage | Create, read, change and delete the brand's webhook endpoint, rotate its secret and send a test event. |
conversations:write, conversations:pause, contacts:read-phone and webhooks:manage are never granted by
default. An admin turns each one on for the key that needs it. A request without the scope an operation needs
answers 403 with the code insufficient_scope.
Send a reply
There are two ways to address a reply. Both need conversations:write, both take the same body, and both return
the same answer.
| Endpoint | Addresses the reply by |
|---|---|
POST /v1/conversations/{id}/messages | The conversation id, for example from message.received. |
POST /v1/conversations/messages | contact_channel_id, or phone for a key with contacts:read-phone. Pass exactly one. |
The second endpoint finds the contact's most recent conversation on the brand's number. If there is none it
answers 404 conversation_not_found; it never starts one.
curl -X POST "https://api.vyg.app/v1/conversations/{id}/messages" \
-H "Authorization: Bearer $VYG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ticket-4821-comment-3" \
-d '{ "text": "Your order ships tomorrow." }'{
"message_id": "0f000000-0000-4000-8000-000000000001",
"status": "queued"
}status is queued when the reply is sent now. It is scheduled, with a scheduled_for time, when the
reply window holds it for later. Both answer 200. The final result arrives by webhook:
message.sent, then message.delivered or message.failed.
The body takes:
text(required): 1 to 1,600 characters.image_url(optional): an HTTPS URL of an image to send as MMS. VYG downloads it once and sends its own copy. An image that is not public, not a supported type or too large answers422 invalid_imageand nothing is sent.
Here is the same call in TypeScript. CI runs this file against the send operation on every change to these docs.
/** An error answer from the VYG API: `{"error": {"code", "message"}}`. */
export class VygApiError extends Error {
constructor(
readonly status: number,
readonly code: string,
message: string,
/** Seconds to wait before retrying, from the Retry-After header of a 429. */
readonly retryAfterSeconds: number | null
) {
super(message);
this.name = 'VygApiError';
}
}
export interface SendReplyResult {
message_id: string;
/** `queued` sends now. `scheduled` is held by the reply window until `scheduled_for`. */
status: 'queued' | 'scheduled';
scheduled_for?: string;
}
export interface SendReplyOptions {
apiKey: string;
conversationId: string;
text: string;
/** Optional HTTPS image URL, sent as MMS. */
imageUrl?: string;
/**
* A key you generate per reply and store with it, such as your ticket comment id. Retrying with the same key and
* the same content within 48 hours returns the original answer instead of sending twice.
*/
idempotencyKey: string;
baseUrl?: string;
fetch?: typeof fetch;
}
/** Send a reply on an existing conversation: POST /v1/conversations/{id}/messages. */
export async function sendReply(options: SendReplyOptions): Promise<SendReplyResult> {
const send = options.fetch ?? fetch;
const baseUrl = options.baseUrl ?? 'https://api.vyg.app';
const response = await send(`${baseUrl}/v1/conversations/${options.conversationId}/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${options.apiKey}`,
'Content-Type': 'application/json',
'Idempotency-Key': options.idempotencyKey,
},
body: JSON.stringify({ text: options.text, ...(options.imageUrl ? { image_url: options.imageUrl } : {}) }),
});
// A gateway error page is not JSON; report it as an API error rather than a parse error.
const body = (await response.json().catch(() => ({
error: { code: 'unknown', message: response.statusText },
}))) as SendReplyResult | { error: { code: string; message: string } };
if (!response.ok || 'error' in body) {
const error = 'error' in body ? body.error : { code: 'unknown', message: response.statusText };
const retryAfter = response.headers.get('Retry-After');
throw new VygApiError(response.status, error.code, error.message, retryAfter ? Number(retryAfter) : null);
}
return body;
}
Idempotency keys
Every send needs an Idempotency-Key header of up to 255 characters. Generate one per reply and store it with the
reply, for example your ticket comment id.
- Sending again with the same key and the same content returns the original answer. No second message is sent.
- Sending the same key with different content (another text, image or recipient) answers
409 idempotency_conflict. - Two requests with the same key at the same time send one message. The second waits for the first and gets the
same answer. If the first is still in progress after that wait, the second answers
409 conflict; retry it with the same key a little later. - A key is kept for 48 hours. Retry a timed-out or failed send with the same key within that time. After 48 hours the key is forgotten, and a send with it is treated as a new reply.
A request with no key, or a key over 255 characters, answers 400 bad_request.
When a send fails
A send that answers 503 unavailable says in its message what happened:
- Nothing went out, retry with the same key. The reply failed before it was handed to the carrier, for example while the image was being stored. No message is sent later and no webhook fires for it. The key is freed, so a retry with the same key sends the reply afresh.
- The send could not be confirmed. The reply may have gone out. Retry with the same key: the retry returns the
same
message_idand never sends a second message.message.sent,message.deliveredormessage.failedreport what happened to it. - Nothing went out, use a new key. A send that stopped part way was later found not to have reached the
carrier. The key keeps returning this failure; to try again, send with a new
Idempotency-Key.
A request that stops before it hands the reply on (for example, it times out) is picked up by a retry with the same key after about a minute, and the reply is sent once.
Errors
Errors use the usual envelope, {"error": {"code", "message"}}. See Errors.
| Status | code | When |
|---|---|---|
400 | bad_request | The body is invalid, the Idempotency-Key header is missing or too long, or both or neither recipient was set. |
401 | unauthorized | No API key, or an unknown, revoked or expired one. |
403 | insufficient_scope | The key lacks the scope, for example contacts:read-phone to send by phone. |
403 | feature_not_enabled | The messaging API is not turned on for the brand, or the brand cannot send SMS. |
404 | conversation_not_found | No conversation to reply to: the brand has no conversation with that id, or the contact has none. A malformed (non-UUID) id answers 404 not_found. |
409 | idempotency_conflict | The Idempotency-Key was already used with different content. |
409 | conflict | A request with the same Idempotency-Key is still in progress. Retry shortly with the same key. |
422 | opted_out | The contact has opted out. Nothing is sent. |
422 | outside_reply_window | The customer's last text is more than 30 days old, or they never texted. The message gives the last text time. |
422 | invalid_image | image_url failed the safety, type or size checks. Nothing is sent. |
429 | rate_limited | Too many requests for the key or the brand. Wait Retry-After seconds. |
503 | unavailable | The reply was not sent, or its send could not be confirmed. See When a send fails. |
400, 403, 404, 409 idempotency_conflict and 422 will fail again until you change the request. For
409 conflict, 429, 500 and 503, retry with the same Idempotency-Key, unless the 503 message tells you
to use a new one.
Reply window
Each reply is timed from the customer's last text in the conversation:
| Customer's last text | What happens |
|---|---|
| Within 24 hours | Sent now, at any hour. |
| 24 hours to 30 days ago | Sent now if it is between 8am and 8pm in the customer's time zone. Otherwise held until 8am their time. |
| More than 30 days ago | Refused with 422 outside_reply_window. |
| Never | Refused with 422 outside_reply_window. |
A held reply answers "status": "scheduled" with scheduled_for, the UTC time it will be sent:
{
"message_id": "0f000000-0000-4000-8000-000000000002",
"status": "scheduled",
"scheduled_for": "2026-11-11T13:00:00.000Z"
}The customer's time zone comes from their phone number. When it is unknown, the brand's time zone is used, and UTC when neither is known. A held reply is checked again for opt-out when it is due, and is not sent if the customer opted out in the meantime.
If the customer texts the brand again while a reply is held, the reply is released and sent shortly after, since
their new text puts the conversation back in the 24-hour window. An opt-out text such as STOP never releases a held
reply, and neither does any text while the contact is unsubscribed. The reply keeps its message_id, and
message.sent reports it when it goes out.
Opt-outs
Customers opt out by texting STOP (or another opt-out keyword) and opt back in with START. Each change fires a
contact.opted_out or contact.opted_in webhook.
A reply to an opted-out contact answers 422 opted_out and is not sent.
Pause
Pause a conversation while your team handles it, so the customer does not get two answers. While the customer is
paused, the brand's agents do not pick them up, and reply flows and off-hours auto-replies do not start. Blasts
and other flows still send. Your API replies still go out, and customer texts still arrive as message.received.
curl -X POST "https://api.vyg.app/v1/conversations/{id}/pause" -H "Authorization: Bearer $VYG_API_KEY"
curl -X POST "https://api.vyg.app/v1/conversations/{id}/resume" -H "Authorization: Bearer $VYG_API_KEY"
curl "https://api.vyg.app/v1/conversations/{id}/pause" -H "Authorization: Bearer $VYG_API_KEY"All three need conversations:pause and return conversation_id, paused and paused_until. A pause applies to
the customer's contact, so it covers every conversation the brand has with them.
A pause lasts 7 days. Pausing again moves paused_until to 7 days from now, and each reply you send through the API
to a paused customer moves it to 7 days after that reply. There are no pause or resume webhook events; read the
state with GET /v1/conversations/{id}/pause.
See Conversation pause for the full rules.
Phone numbers
Contacts are identified by contact_id and contact_channel_id. Phone numbers are left out of every payload by
default. A key with contacts:read-phone can:
- look up a contact's number with
GET /v1/contacts/{id}/phone, which returns{"id", "phone"}with the number in E.164 ornull; - send by
phoneonPOST /v1/conversations/messages; - turn on
include_phoneon the webhook endpoint, which addsphoneto its payloads.
Each lookup and each change that turns on include_phone is recorded in the audit log. The log never stores the
number.
Read conversations
Use the conversation endpoints, with conversations:read, to load a conversation when a webhook arrives or to
check its current state:
GET /v1/conversationslists the brand's conversations. Passcontact_idto list one contact's conversations.GET /v1/conversations/{id}reads one conversation.GET /v1/conversations/{id}/messageslists its messages.
Lists return { data, next_cursor }. Pass next_cursor back as cursor until it is null. See
Pagination.
There is no "changed since" filter. If your endpoint was down for longer than the retry window, read the conversations you have open tickets for to catch up.
Rate limits
Limits apply per API key. Sends also have a limit for the whole brand, shared by all of the brand's keys: 300 sends
per minute across both send endpoints, on top of each key's 60. Every response from a limited endpoint carries
X-RateLimit-Limit (requests allowed in the key's window) and X-RateLimit-Reset (the window in seconds). Over a
limit, the API answers 429 rate_limited with a Retry-After header in seconds. A 429 from the brand limit
reports 300 in X-RateLimit-Limit.
| Operation | Limit per key |
|---|---|
| Send a reply (both send endpoints share one limit) | 60 requests per minute |
| Pause and resume (shared) | 60 requests per minute |
| Read the pause state | 120 requests per minute |
| Look up a phone number | 120 requests per minute |
| Create, change or delete the webhook endpoint, rotate, or test it | 30 requests per minute |
| Read the webhook endpoint | 120 requests per minute |
Each webhook write operation has its own 30-per-minute limit; they do not share one.
| Operation | Limit per brand, all keys together |
|---|---|
| Send a reply (both send endpoints share one limit) | 300 requests per minute |
Wait the Retry-After time, then retry. Retrying a send with the same Idempotency-Key is always safe. See
Rate limits.