VYG Docs
Messaging API

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:

  1. Create an API key with the scopes below.
  2. Create the brand's webhook endpoint for message.received and the delivery events.
  3. When a customer texts in, message.received arrives with the conversation id. Open a ticket.
  4. Pause the conversation so the brand's agents and automated replies stay out while your team handles it.
  5. Reply with POST /v1/conversations/{id}/messages. message.sent, then message.delivered or message.failed, report the result.
  6. 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

ScopeAllows
conversations:readList conversations and read their messages.
conversations:writeSend replies.
conversations:pausePause and resume conversations, and read their pause state.
contacts:readRead contacts.
contacts:read-phoneLook up a contact's phone number, send by phone number and add phone to webhook payloads.
webhooks:manageCreate, 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.

EndpointAddresses the reply by
POST /v1/conversations/{id}/messagesThe conversation id, for example from message.received.
POST /v1/conversations/messagescontact_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 answers 422 invalid_image and 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_id and never sends a second message. message.sent, message.delivered or message.failed report 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.

StatuscodeWhen
400bad_requestThe body is invalid, the Idempotency-Key header is missing or too long, or both or neither recipient was set.
401unauthorizedNo API key, or an unknown, revoked or expired one.
403insufficient_scopeThe key lacks the scope, for example contacts:read-phone to send by phone.
403feature_not_enabledThe messaging API is not turned on for the brand, or the brand cannot send SMS.
404conversation_not_foundNo 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.
409idempotency_conflictThe Idempotency-Key was already used with different content.
409conflictA request with the same Idempotency-Key is still in progress. Retry shortly with the same key.
422opted_outThe contact has opted out. Nothing is sent.
422outside_reply_windowThe customer's last text is more than 30 days old, or they never texted. The message gives the last text time.
422invalid_imageimage_url failed the safety, type or size checks. Nothing is sent.
429rate_limitedToo many requests for the key or the brand. Wait Retry-After seconds.
503unavailableThe 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 textWhat happens
Within 24 hoursSent now, at any hour.
24 hours to 30 days agoSent now if it is between 8am and 8pm in the customer's time zone. Otherwise held until 8am their time.
More than 30 days agoRefused with 422 outside_reply_window.
NeverRefused 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 or null;
  • send by phone on POST /v1/conversations/messages;
  • turn on include_phone on the webhook endpoint, which adds phone to 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/conversations lists the brand's conversations. Pass contact_id to list one contact's conversations.
  • GET /v1/conversations/{id} reads one conversation.
  • GET /v1/conversations/{id}/messages lists 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.

OperationLimit 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 state120 requests per minute
Look up a phone number120 requests per minute
Create, change or delete the webhook endpoint, rotate, or test it30 requests per minute
Read the webhook endpoint120 requests per minute

Each webhook write operation has its own 30-per-minute limit; they do not share one.

OperationLimit 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.

On this page