VX Agents

API directory · Messaging & SMS

Sinch Conversation Messages & Contacts

v1.0.0 · 13 endpoints · 0 connections · shared by vx.ai

Send, read and follow up on customer chats through one Sinch Conversation API app, whether the customer is on WhatsApp, RCS, SMS, Messenger or Viber. Check which channels a contact can receive, send text, media or choice messages, page through conversation history, and keep contact records and their channel identities up to date.

Connect this API to an AI agent Browse all specs

What you can do with Sinch Conversation Messages & Contacts via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /v1/projects/{project_id}/apps listApps List the Conversation API apps in the project
POST /v1/projects/{project_id}/capability:query queryCapability Check which channels a contact or phone number can receive messages on
POST /v1/projects/{project_id}/messages:send sendMessage Send a text, media, choice or template message to a contact
GET /v1/projects/{project_id}/messages listMessages List messages, filtered by conversation, contact or time
GET /v1/projects/{project_id}/messages/{message_id} getMessage Get one message
GET /v1/projects/{project_id}/conversations listConversations List conversations of an app or a contact
GET /v1/projects/{project_id}/conversations:recent listRecentConversations List recent conversations with their latest message
GET /v1/projects/{project_id}/conversations/{conversation_id} getConversation Get one conversation
POST /v1/projects/{project_id}/conversations/{conversation_id}:stop stopConversation End an active conversation
GET /v1/projects/{project_id}/contacts listContacts List contacts, or find one by channel identity
POST /v1/projects/{project_id}/contacts createContact Create a contact with one or more channel identities
GET /v1/projects/{project_id}/contacts/{contact_id} getContact Get a contact and its channel identities
PATCH /v1/projects/{project_id}/contacts/{contact_id} updateContact Update a contact's name, email or channel identities

Authentication

Basic

HTTP Basic

HTTP basic auth with a Sinch access key: the Key ID is the username and the Key Secret is the password.

How to get a credential

  1. Sign in to the Sinch Customer Dashboard (dashboard.sinch.com).
  2. Open Settings > Access Keys and click Create Access Key.
  3. Name it (e.g. VX Agents), then copy the Key ID and Key Secret; the secret is shown only once.
  4. Note your Project ID on the same page and the App ID of your Conversation API app (Conversation API > Apps); you pass both as parameters.

Permissions used

Access keys have no scopes; a key can use every Conversation API app in its project.

Credential Operations
Project access key all operations: listApps, queryCapability, sendMessage, listMessages, getMessage, listConversations, listRecentConversations, getConversation, stopConversation, listContacts, getContact, createContact, updateContact

Common errors

Status Meaning Fix
401 Wrong key id or secret Create a new access key and store both parts.
403 The key belongs to another project, or the region host does not match the app Use the project's own key and the app's region (us, eu or br).
400 Invalid request, e.g. a recipient with no identity on the chosen channel Read error.message; check the contact's channel identities.
404 Unknown project, app, contact or conversation id Look ids up with listApps and listContacts.
429 Rate limit (per project) exceeded Wait and retry with backoff.

Store the key id and secret as a basic-auth credential in VX Agents; never paste them into chat.

Usage guide

Setup

  • Credential: a Sinch access key (Dashboard > Settings > Access Keys): Key ID as username, Key Secret as password, stored as a basic-auth credential.
  • Preset parameters worth pinning: project_id (same page as the keys) and the app_id of your Conversation API app. Set the region server variable (us, eu or br) to the region the app was created in; a mismatch fails.

Message a customer

  1. Find the contact: listContacts with channel + identity (e.g. WHATSAPP and +4915112345678) or external_id; getContact shows its channel identities. createContact needs channel_identities and language (e.g. EN_US).
  2. Optional: queryCapability with app_id and recipient to check which channels can reach them.
  3. sendMessage with app_id, recipient and message:
    • recipient: {"contact_id": "..."} or {"identified_by": {"channel_identities": [{"channel": "WHATSAPP", "identity": "+4915112345678"}]}}.
    • message: {"text_message": {"text": "Hi!"}}, or media_message (url), choice_message, card_message, location_message, template_message.
    • Optional channel_priority_order, e.g. ["WHATSAPP", "SMS"], to fall back when a channel fails. This sends a real (billed) message: show the user the text and recipient and get a yes first.
  4. The response gives a message_id; delivery status arrives by webhook, and getMessage shows the stored message.

Read the history

  1. listRecentConversations (needs app_id) for the latest conversations with their last message; listConversations with contact_id or only_active=true.
  2. listMessages with conversation_id or contact_id, start_time/end_time, direction (TO_APP = from the customer); page with page_size and page_token.
  3. getConversation; stopConversation ends an active one (confirm first).

Good to know

  • Ids are ULIDs (26 characters). Timestamps are RFC 3339 UTC (2026-10-22T09:00:00Z).
  • Phone identities use E.164 (+ and country code).
  • WhatsApp only allows free text within 24 hours of the customer's last message; after that send an approved template_message.
  • updateContact changes only the fields named in update_mask when given.
  • Carousel, list and contact-card messages and per-channel overrides are left out to keep the tool small.

Source: Sinch Conversation API reference (https://developers.sinch.com/docs/conversation/api-reference), checked 2026-10-22.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Sinch Conversation Messages & Contacts” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Microsoft Teams Chats & Channels — Catch up on Microsoft Teams and answer without switching apps: read channel threads and their replies, read one-on-one …
  • Telnyx Messaging — Send, schedule and track SMS/MMS messages through Telnyx, look up phone numbers before sending, and review messaging pr…
  • Infobip SMS — When an appointment reminder or a one-off promo has to go out by text: preview how Infobip will split and encode the me…
  • Twilio Lookup (phone validation) — Lets an agent check whether a phone number is real and correctly formatted, convert it to E.164, and look up its line t…
  • LINE Messaging API — For shops and clinics that talk to customers on a LINE Official Account: answer chats with free reply tokens, push or b…
  • Twilio Voice Calls & Recordings — Place, redirect and end phone calls through Twilio Programmable Voice, start or pause call recordings, and pull call lo…