VYG Docs

Conversations

GET/v1/conversations/search

Scope: conversations:read.

Find customer conversations about a topic. Filter by category or tag.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

query*string
category?string
tag?string
threshold?number
limit?integer

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/conversations/search?query=string"
{  "data": [    {      "conversation_id": "string",      "similarity": 0,      "text_content": "string",      "category": "string",      "tag": "string",      "customer": "string"    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/conversations

Scope: conversations:read.

View conversations, newest first. Pass contact_id to scope to one customer's conversations.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer
cursor?string
contact_id?string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/conversations"
{  "data": [    {      "id": "string",      "created_at": "string",      "updated_at": "string",      "last_engaged_at": "string",      "last_received_at": "string",      "awaiting_reply": true,      "cart_value": "string",      "cart_currency": "string",      "customer": {        "name": "string",        "handle": "string"      },      "workflow": {        "name": "string",        "type": "string"      },      "checkout_state": "string",      "last_message": {        "body": "string",        "direction": "string",        "created_at": "string"      }    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/conversations/{id}

Scope: conversations:read.

View a conversation by ID. Returns 404 if it cannot be found.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/conversations/string"
{  "id": "string",  "created_at": "string",  "updated_at": "string",  "last_engaged_at": "string",  "last_received_at": "string",  "awaiting_reply": true,  "cart_value": "string",  "cart_currency": "string",  "customer": {    "name": "string",    "handle": "string"  },  "workflow": {    "name": "string",    "type": "string"  },  "checkout_state": "string",  "last_message": {    "body": "string",    "direction": "string",    "created_at": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/conversations/{id}/messages

Scope: conversations:read.

View messages in a conversation, oldest first. Returns 404 if the conversation cannot be found.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

limit?integer
cursor?string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/conversations/string/messages"
{  "data": [    {      "id": "string",      "direction": "string",      "body": "string",      "status": "string",      "created_at": "string",      "updated_at": "string",      "sent_at": "string",      "scheduled_for": "string"    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/conversations/{id}/messages

Scope: conversations:write.

Send a reply on an existing conversation, addressed by its id. Requires conversations:write, the messaging-API beta, and an Idempotency-Key header (<= 255 chars). Returns the queued message id; final delivery status arrives by webhook. Repeating a key with the same content returns the original response; a different content returns 409.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/conversations/string/messages" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'
{  "message_id": "string",  "status": "queued",  "scheduled_for": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/conversations/messages

Scope: conversations:write.

Send a reply addressed by contact_channel_id (or, with contacts:read-phone, by phone), resolving to that contact's existing conversation on the brand's number. Returns conversation_not_found when there is none; never starts a conversation. Same auth, idempotency and semantics as POST /conversations/{id}/messages.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/conversations/messages" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'
{  "message_id": "string",  "status": "queued",  "scheduled_for": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/conversations/{id}/pause

Scope: conversations:pause.

Whether the conversation's contact is paused, and until when. Requires conversations:pause and the messaging-API beta.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/conversations/string/pause"
{  "conversation_id": "string",  "paused": true,  "paused_until": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/conversations/{id}/pause

Scope: conversations:pause.

Pause the brand's agent queue, assignment rules, reply flows and off-hours auto-replies for the conversation's contact while your help desk handles them. Blasts, marketing flows and API replies still go out. The pause lasts 7 days and each API reply pushes it forward; pausing again also pushes it forward. Requires conversations:pause and the messaging-API beta.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/conversations/string/pause"
{  "conversation_id": "string",  "paused": true,  "paused_until": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/conversations/{id}/resume

Scope: conversations:pause.

End the pause on the conversation's contact so the brand's agents and automated replies act on it again. A customer text nobody answered goes back in the agent queue. Idempotent: resuming a conversation that is not paused returns paused: false. Requires conversations:pause and the messaging-API beta.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/conversations/string/resume"
{  "conversation_id": "string",  "paused": true,  "paused_until": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/contacts/{id}/phone

Scope: contacts:read-phone.

The contact’s SMS phone number. Needs the contacts:read-phone permission, which exposes customer phone numbers; every call is recorded in the key’s audit log.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/string/phone"
{  "id": "string",  "phone": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/contacts

Scope: contacts:read.

View contacts, oldest first.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer
cursor?string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts"
{  "data": [    {      "id": "string",      "given_name": "string",      "family_name": "string",      "name": "string",      "source": "string",      "accepts_sms_marketing": true,      "created_at": "string",      "updated_at": "string"    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/contacts/{id}

Scope: contacts:read.

View a contact by ID. Returns 404 if it cannot be found.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/string"
{  "id": "string",  "given_name": "string",  "family_name": "string",  "name": "string",  "source": "string",  "accepts_sms_marketing": true,  "created_at": "string",  "updated_at": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/brand/insights

Scope: insights:read.

See common themes in customer conversations, including checkout issues, post-purchase concerns and product questions. Filter by category, tag or date.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

category?string
tag?string
limit?integer
day_limit?integer
cursor?string

next_cursor from the previous page.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brand/insights"
{  "data": [    {      "id": "string",      "category": "string",      "tag": "string",      "topic": "string",      "body": "string",      "updated_at": "string"    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/brand/insights/{insight_id}/conversations

Scope: insights:read.

View the conversations behind an insight, with customer details and message previews. Use an ID from list_conversation_insights.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

insight_id*string

Query Parameters

limit?integer
cursor?string

next_cursor from the previous page.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brand/insights/string/conversations"
{  "data": [    {      "conversation_id": "string",      "created_at": "string",      "customer": {        "name": "string",        "phone": "string"      },      "checkout_state": "string",      "message_preview": "string"    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/checkouts/{checkout_id}/purchase-likelihood

Scope: conversations:read. MCP tool: get_checkout_purchase_likelihood.

Read the cart and per-product purchase likelihood for a checkout of the calling brand.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

checkout_id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/checkouts/497f6eca-6276-4993-bfeb-53cbbbba6f08/purchase-likelihood"
{  "checkout_id": "a0db819d-3316-4040-b9b7-2c905552650c",  "purchase_likelihood": {    "probability": 0,    "band": "string",    "has_score": true,    "computed_at": "string"  },  "items": [    {      "product_key": "string",      "title": "string",      "probability": 0,      "band": "string",      "computed_at": "string"    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/conversations/{conversation_id}/trace

Scope: conversations:read.

Trace a conversation back to what started it and forward to what it produced: the triggering event (checkout, cart, custom event, order, subscription event or signup list), the campaign and each step of its run (entered, skipped with the reason, sent, failed), the messages by status with the next scheduled send time (messages wait for quiet hours or a wait step), and whether it led to a recovered order. Use it to answer "why did this customer get this text?" or "did this conversation recover the sale?".

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

conversation_id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/conversations/string/trace"
{  "conversation_id": "string",  "created_at": "string",  "contact_id": "string",  "campaign": {    "id": "string",    "name": "string",    "type": "string"  },  "trigger": {    "kind": "checkout",    "event_type": "string",    "event_id": "string",    "checkout": {      "id": "string",      "state": "string",      "total": {        "amount": 0,        "currency": "string"      },      "created_at": "string",      "abandoned_at": "string",      "completed_at": "string"    },    "custom_event": {      "id": "string",      "type": "string",      "name": "string",      "source": "string",      "external_event_id": "string",      "received_at": "string"    },    "order": {      "id": "string",      "number": "string",      "total": {        "amount": 0,        "currency": "string"      },      "created_at": "string"    },    "subscription_event": {      "id": "string",      "type": "string",      "triggered_at": "string"    },    "list_id": "string"  },  "run": [    {      "at": "string",      "state": "string",      "step": "string",      "step_id": "string",      "event_type": "string",      "event_id": "string",      "campaign_id": "string",      "campaign_name": "string",      "conversation_id": "string",      "contact_id": "string",      "reason": {        "code": "string",        "label": "string",        "level": "string",        "rule": "string"      },      "error": "string"    }  ],  "messages": {    "total": 0,    "by_status": [      {        "status": "string",        "count": 0      }    ],    "next_scheduled_for": "string",    "first_sent_at": "string",    "last_sent_at": "string"  },  "outcome": {    "recovered": true,    "recovered_amount": {      "amount": 0,      "currency": "string"    },    "goals": [      {        "at": "string",        "conversation_id": "string",        "campaign_id": "string",        "order_id": "string",        "order_number": "string",        "amount": {          "amount": 0,          "currency": "string"        },        "attribution": "string",        "billing_status": "string",        "recovered": true      }    ]  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}