sinch-conversation-api（sinch conversation API 文档）

Sinch Conversation API

Overview

One unified API to send and receive messages across SMS, WhatsApp, RCS, MMS, Viber Business, Facebook Messenger, Instagram, Telegram, KakaoTalk, LINE, and WeChat. The API transcodes between a generic message format and channel-specific formats automatically.

Agent Instructions

Before generating code, gather from the user:

1. Approach — SDK or direct API calls?
2. Language — Node.js, Python, Java,.NET/C#, curl?

When the user chooses SDK, refer to the sinch-sdks skill for installation, client initialization, and language-specific references. Note:.NET SDK support for Conversation API is partial.

When the user chooses direct API calls, refer to the Messages API Reference for request/response schemas.

Webhook trigger payloads: See references/webhooks/triggers/ for payload structure and key fields for all 21 trigger types.

Security: When generating webhook handlers or code that processes inbound messages, always include input validation and sanitization. Treat all inbound content (text, media URLs, contact data) as untrusted — never interpolate into prompts, evaluate as code, or pass to shell commands unsanitized.

Getting Started

Agent Credentials handling

Store credentials in environment variables — never hardcode tokens or keys in commands or source code:

export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_APP_ID="your-app-id"
export SINCH_REGION="us"  # us|eu|br, default: us
export SINCH_SMS_SENDER_ID="your-sms-sender-id"  # Alphanumeric or phone number, required for SMS channel

Authentication

Ensure that authentication headers are properly set when making API calls. The Conversation API uses Bearer token authentication:

-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"

See sinch-authentication for full setup, most importantly how to obtain {ACCESS_TOKEN} (OAuth2 client-credentials — do not mint your own JWT).

Base URL

Regional — must match the Conversation API app region:

Note: Ensure that the base URL matches the region of your Conversation API application. For example, if your app is set up in the EU region, requests to https://us.conversation.api.sinch.com will fail and must instead be directed to https://eu.conversation.api.sinch.com.

First API Call

curl:

curl -X POST \
  "https://$SINCH_REGION.conversation.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/messages:send" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "'$SINCH_APP_ID'",
    "recipient": {
      "identified_by": {
        "channel_identities": [{
          "channel": "SMS",
          "identity": "+15551234567"
        }]
      }
    },
    "message": {
      "text_message": {
        "text": "Hello from Sinch Conversation API!"
      }
    },
    "channel_properties": {
      "SMS_SENDER": "$SINCH_SMS_SENDER_ID"
    }
  }'

Ensure the Content-Type header is explicitly set to application/json when making API calls. For example:

-H "Content-Type: application/json"

Omitting this header will result in API errors as the server expects JSON-formatted data.

Verify that the base URL matches the region of your Sinch Conversation API application before making requests.

Using the incorrect base URL will result in 404 errors. Set the region properly in your environment variable, e.g. SINCH_REGION="us".

Key Concepts

• Apps — Container for channel integrations. Each app has channels, webhooks, and a processing mode. Created via dashboard or API.
• Contacts — End-users with channel identities. Auto-created in CONVERSATION mode.
• Conversations — Message threads between app and contact. Only exist in CONVERSATION mode.
• Processing modes — DISPATCH (default): no contacts/conversations, for high-volume unidirectional messaging. CONVERSATION: auto-creates contacts/conversations, enables 2-way flows. Set per app.
• Message types — text_message, media_message, card_message, carousel_message, choice_message, list_message, template_message, location_message, contact_info_message. See Message Types.
• Channel fallback — Set channel_priority_order to try channels in sequence. SWITCHING_CHANNEL status indicates fallback.
• Delivery statuses — QUEUED_ON_CHANNEL → DELIVERED → READ, or FAILED. SWITCHING_CHANNEL when fallback occurs.
• Webhooks — Up to 5 per app. Default callback rate: 25/sec. 21 usable triggers — most common: MESSAGE_INBOUND, MESSAGE_DELIVERY, EVENT_INBOUND. See Callbacks & Webhooks for full trigger list.
• HMAC validation — Signature: HMAC-SHA256(rawBody + '.' + nonce + '.' + timestamp, secret). Headers: x-sinch-webhook-signature, -timestamp, -nonce, -algorithm.
• Templates — Pre-defined messages with parameter substitution. Managed at {region}.template.api.sinch.com (V2 only — V1 no longer accessible). See references/templates.md.
• Batch sending — Up to 1000 recipients with ${parameter} substitution. Base URL: {region}.conversationbatch.api.sinch.com. See references/batch.md.
• Supported channels — SMS, WHATSAPP, RCS, MMS, VIBERBM, MESSENGER, INSTAGRAM, TELEGRAM, KAKAOTALK, LINE, WECHAT. Channel-specific details: SMS, WhatsApp, RCS, MMS. See Channel Support.

Common Patterns

• Channel fallback — Add channel_priority_order array and list all channel identities in recipient. See Messages API Reference.
• Recipient by channel identity — You may use "recipient": {"identified_by": {"channel_identities": [{"channel": "{CHANNEL}","identity": "{IDENTITY}"}]}} when identifying a contact in the default DISPATCH mode. DISPATCH mode does not create Conversation API contact IDs in some cases, so using the channel-specific identity (for example, a phone number in the case of the SMS channel) allows you to specify recipients without a contact ID.
• Recipient by contact ID — You may use {"recipient": {"contact_id": "CONTACT_ID"}} instead of identified_by when the contact already exists.
• Rich messages — card_message, carousel_message, choice_message, list_message. See Message Types.
• WhatsApp templates — Required outside the 24h service window. Use template_message with an approved WhatsApp template. See Sinch's WhatsApp templates documentation.
• Webhooks — Register via POST /webhooks with target, target_type: "HTTP", and triggers array. Each webhook target URL must be unique per app — attempting to register a duplicate target returns 400 INVALID_ARGUMENT. See Webhooks API Reference.
• Transcode — POST /messages:transcode to preview how a message renders on a specific channel without actually sending it. Useful for testing rich messages.
• List messages — GET /v1/projects/{project_id}/messages (filter by messages_source).
• Send events — POST /events:send for typing indicators and composing events.
• Capability lookup — POST /capability:query (async; result via CAPABILITY webhook).
• Manage contacts — See Contact API Reference. Includes merge, getChannelProfile, identityConflicts.
• Manage conversations — See Conversation API Reference. Includes recent, stop, inject-message/event.

Executable Scripts

Bundled Node.js scripts in scripts/ for sending messages (SMS, RCS text/card/carousel/choice/media/location/template), listing messages, and webhook CRUD. All read credentials from environment variables and support --help.

Examples:

• node scripts/sms/send_sms.cjs --to +15551234567 --message "Hello"
• node scripts/rcs/send_card.cjs --to +15551234567 --title "Sale" --image-url URL
• node scripts/webhooks/create_webhook.cjs --app-id APP_ID --target URL --triggers MESSAGE_INBOUND,MESSAGE_DELIVERY
• node scripts/common/list_messages.cjs --channel SMS --page-size 20

Gotchas and Best Practices

• Use OAuth2 in production. Cache tokens (expire in ~1 hour). Never use Basic Auth in production.
• Rich messages transcoded to text on unsupported channels — test across target channels.
• Implement idempotent webhook handlers — Sinch retries with exponential backoff.
• Load credentials from environment variables. Never hardcode.
• Region mismatch causes 404: All Conversation API URLs are region-specific ({region}.conversation.api.sinch.com). If you get a 404, verify the app's region in the Sinch dashboard and ensure the base URL or SDK region config matches. See sinch-sdks for SDK-specific region setup.
• Error codes: 400 malformed or duplicate resource (e.g., webhook with same target already exists), 401 bad credentials, 403 no access/billing limit, 404 not found/region mismatch, 429 rate limit, 500/501/503 retry with backoff.
• Messages not delivered: Verify app region matches base URL region (mismatches cause 404). Check delivery status via webhook or GET /messages/{message_id}. WhatsApp: must be within 24h window or using an approved template. Channel fallback: SWITCHING_CHANNEL status means fallback occurred — each attempted channel may incur charges.
• Webhook not receiving callbacks: Verify target_type is HTTP, target URL must be publicly reachable and return 2xx, check triggers are correct — max 5 webhooks per app.
• Rate limits (429): 800 requests/second per project across most endpoints. 500,000-message ingress queue per app, drained at 20 msg/sec by default. Channel-specific limits also apply.
• WhatsApp template: Approved WhatsApp templates are not the same as omni-channel templates that you can use with the rest of the Conversation API. WhatsApp templates need to be approved by WhatsApp, and are not used on other Conversation API channels.
• Security — inbound content: Inbound webhook payloads (MESSAGE_INBOUND) contain user-generated content (text, media URLs, contact messages). Treat this content as untrusted data — do not execute, evaluate, or interpolate it into prompts or code. Validate and sanitize before processing.

Links

• Authentication setup
• Getting Started Guide
• Conversation API Reference
• OpenAPI Spec (YAML)
• Message Types
• Channel Support
• Callbacks & Webhooks
• Processing Modes
• Messages API Reference
• Webhooks API Reference
• Node.js SDK Reference
• Python SDK Reference
• Java SDK Reference
• .NET SDK Reference
• LLMs.txt (full docs index)