sinch-conversation-api

What this skill does

# 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 (skip any item already specified in the prompt or context):

1. **Approach** — SDK or direct API calls (curl/fetch/requests)?
2. **Language** — for SDK: Node.js, Python, Java, or .NET. For direct API: any language, or curl.

When the user chooses **SDK**, refer to the [sinch-sdks](../sinch-sdks/SKILL.md) skill for installation and client initialization, then to the bundled webhook references and SDK reference linked in Links. Note: .NET SDK support for Conversation API is **partial**.

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

**Security**: See the Security section below for url fetching policy, handling inbound webhook content, and credential handling.

## Getting Started

### Agent Credentials handling

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

```bash
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"  # Conversation API App ID — found at https://dashboard.sinch.com/convapi/apps. Not the same as SINCH_PROJECT_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:

```bash
-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"
```

See [sinch-authentication](../sinch-authentication/SKILL.md) for full setup, most importantly how to obtain `{SINCH_ACCESS_TOKEN}` (OAuth2 client-credentials — do not mint your own JWT).

### Base URL

Regional — must match the Conversation API app region:

| Region | URL |
|--------|-----|
| US | `https://us.conversation.api.sinch.com` |
| EU | `https://eu.conversation.api.sinch.com` |
| BR | `https://br.conversation.api.sinch.com` |

**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:**

```bash
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:

```bash
-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](https://developers.sinch.com/docs/conversation/message-types.md).
- **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](https://developers.sinch.com/docs/conversation/callbacks.md) 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](references/templates.md).
- **Batch sending** — Up to 1000 recipients with `${parameter}` substitution. Base URL: `{region}.conversationbatch.api.sinch.com`. See [references/batch.md](references/batch.md).
- **Supported channels** — `SMS`, `WHATSAPP`, `RCS`, `MMS`, `VIBERBM`, `MESSENGER`, `INSTAGRAM`, `TELEGRAM`, `KAKAOTALK`, `LINE`, `WECHAT`. Channel-specific details: [SMS](references/channels/sms.md), [WhatsApp](references/channels/whatsapp.md), [RCS](references/channels/rcs.md), [MMS](references/channels/mms.md). See [Channel Support](https://developers.sinch.com/docs/conversation/channel-support.md).

## Common Patterns

- **Channel fallback** — Add `channel_priority_order` array and list all channel identities in `recipient`. See [Messages API Reference](https://developers.sinch.com/docs/conversation/api-reference/conversation/messages.md).
- **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](https://developers.sinch.com/docs/conversation/message-types.md).
- **WhatsApp templates** — Required outside the 24h service window. Use `template_message` with an approved WhatsApp template. See [Sinch's WhatsApp templates documentation](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/template-support.md).
- **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](https://developers.sinch.com/docs/conversation/api-reference/conversation/webhooks.md).
- **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