VYG Docs

Conversations

Search conversations

GET/v1/conversations/search

Scope: conversations:read. MCP tool: search_conversations.

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"  }}

Recent conversations

GET/v1/conversations

Scope: conversations:read. MCP tool: list_conversations.

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 a conversation

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"  }}

Conversation messages

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"  }}

List contacts

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"  }}

Contact

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"  }}

Conversation insights

GET/v1/brand/insights

Scope: insights:read. MCP tool: list_conversation_insights.

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"  }}

Conversations behind an insight

GET/v1/brand/insights/{insight_id}/conversations

Scope: insights:read. MCP tool: list_insight_conversations.

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"  }}

Why this conversation happened

GET/v1/conversations/{conversation_id}/trace

Scope: conversations:read. MCP tool: get_conversation_trace.

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"  }}

Brand

Previous Page

Customers

Next Page