> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/conversations/channel-manager.md).

# Channel Manager

Channel Manager operation reference: authentication, SMS, email, iMessage, WhatsApp, and voice contracts, with the limits and errors of each.

Channel Manager connects your application to phone calls, SMS/MMS, email, iMessage, and WhatsApp. Your team configures and runs the agent, and Channel Manager provides the provisioned senders, channel APIs, and delivery records. You do not need a Concurrence workspace, agent, service, or Developer Console.

This page is the operation reference. For numbered steps with copy-paste requests, including creating a setup, A2P registration, numbers, use cases, SMS, voice, webhooks, and campaign metrics, use [Integrate Channel Manager Through the API](https://docs.concurrence.com/developer-guide/reference-guides/integrate-channel-manager.md).

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-b7a047d1e3db269110f8fb94c50680264e096cb6%2Fchannel-manager-ownership.svg?alt=media" alt="Channel Manager supplies provisioned channel APIs and records. The customer application owns its agent, consent decisions, business records, and workflow, including reply and event handling."><figcaption><p>Channel provisioning is a prerequisite, not an API call that starts a conversation.</p></figcaption></figure>

Your application owns the conversation, consent decisions, scheduling, and business records. If a Concurrence workspace service handles the conversation, use the [service binding](#service-binding). Webchat is separate. To embed a Concurrence agent, see [Serve an Agent From a Web App](https://docs.concurrence.com/developer-guide/platform-api/conversations/serve-agent-from-web-app.md).

A **setup** is the access boundary for channel resources, and a **use case** is the provisioned purpose, channel, and routing within it. A customer can have several setups, and a setup is not a workspace. Use Channel Manager-issued IDs, not provider identifiers, in your records.

## Standalone API

The base URL is `https://channels.api-us.concurrence.com`. The [OpenAPI schema](https://channels.api-us.concurrence.com/openapi.json) is separate from the workspace Platform API. Use the host assigned during onboarding and keep it in configuration.

Provisioning operations are in the schema and walked through in the guide: `/v1/twilio-setup` (setup and review status), `/v1/twilio-setup/{setup_id}/bundle/...` (A2P messaging profile and brand registration), `/v1/twilio-setup/{setup_id}/phone-number` (search, purchase, toll-free verification, assignment), `/v1/use-case`, and `/v1/use-case/{use_case_id}/a2p-campaign`.

### Authenticate

Exchange the client ID and secret for a one-hour bearer token. There is no refresh token. Ungranted scopes are omitted from the returned `scope`. Access is restricted by operation scope and setup ID. Keep secrets on your server, with separate clients for runtime and administration. Rotating a secret blocks new exchanges with it. Issued tokens stay valid until expiry.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/oauth/token" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Inspect Provisioned Use Cases

Check the channel, sender, and receiver URL. The detailed read returns `phone_numbers`, and the list leaves it empty.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/use-case" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/use-case/{use\_case\_id}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Send and Reconcile SMS

A successful send means the provider accepted the message. Read it again for delivery or error information. The send has no idempotency key, so [reconcile after a timeout](https://docs.concurrence.com/developer-guide/reference-guides/reconcile-channel-manager.md). Listing needs `setup_id` and `use_case_id` or `peer_phone_number`. `peer_phone_number` filters, and records report `from_number` and `to_number`. MMS uses the same send with attachments.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms/" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms/{message\_id}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms/{sms\_id}/attachment/{attachment\_name}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### SMS Recipient Opt-In and Opt-Out

`sms:consent:read` reads opt-outs, and `sms:consent:write` sends an opt-in message or clears a setup-wide opt-out. An `sms:send` grant alone does not authorize them. Numbers are E.164.

**Opt-in message.** Takes `use_case_id` and `to_phone_number` and sends the confirmation registered for the use case. Returns `201` without a message ID, and repeating it is a no-op. A `409` means an active setup-wide opt-out, which it cannot reverse. The record shows the confirmation was accepted, not delivered or consented.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms/opt-in" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

**Read opt-outs.** Takes `setup_id`, optional `user_phone_number`, and `include_deleted=true` for cleared records. Pages with `limit` and `continuation_token`. An empty result is not proof of consent.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms/opt-out" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

**Clear a setup-wide opt-out.** Takes `setup_id`, `user_phone_number`, and a non-empty `reason`. Returns `204`, `404` without an active opt-out, or `409` while a toll-free line still has one (the recipient texts `START` or `UNSTOP` first).

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/sms/remove-setup-opt-out" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

Recipients opt out with the supported [SMS keywords](https://docs.concurrence.com/channels/sms#opt-out-and-re-subscription). The API has no operation to create an opt-out.

### Send and Reconcile Email

Send inline HTML or a stored template. An unsubscribable use case must reference `unsubscribe_link` and `unsubscribe_from_all_link`. Otherwise, inline HTML has no template variables. Sending needs verified DKIM, MAIL FROM, and DMARC records (`409` otherwise). `inbound_mode` (`send_only`, `replies_only`, `all_inbound`) controls inbound, and a receiving mode needs verified inbound MX. Reply with `reply_to_inbound_email_id` from the same use case. Opens and clicks are tracking signals, not outcomes. See [Email](https://docs.concurrence.com/channels/email#use-cases-and-sender-identities).

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/{email\_id}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/event" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/{email\_id}/body" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/{email\_id}/attachment/{filename}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Manage Email Templates

Templates belong to one email use case, with unique names. Authoring needs `email:template:write`, reads need `email:template:read`, and sending needs `email:send`. Supply the non-reserved `required_subject_variables` and `required_body_variables` as strings in `template_parameters`. See the [template walkthrough](https://docs.concurrence.com/developer-guide/reference-guides/channel-manager-email-templates.md).

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/template" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/template" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/template/{email\_template\_id}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/template/{email\_template\_id}" method="put" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/email/template/{email\_template\_id}" method="delete" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Send and Reconcile iMessage

Send text, one media file, or both. The service prefers a line the contact has replied to. Delivery can fall back to SMS, so read `service`, `was_downgraded`, and the delivery fields. Before the contact replies, messages are at most 300 characters with no media, links, phone numbers, or email addresses, and stop after six sent or delivered. A restriction or a setup-wide opt-out returns `422`, and the recipient texts `START` to opt back in. The endpoint has no idempotency key.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/imessage/" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/imessage/{message\_id}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/imessage" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/imessage/{message\_id}/media" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Reply Through WhatsApp

Use the business-scoped `caller_ref` from the inbound event as the recipient, within 23 hours of their message. The operation sends free-form messages, not templates. The schema has no WhatsApp read operation.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/whatsapp/" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Control Voice Calls

Creating a call reserves a `call_ref` and sender number and dials nobody. A `media` participant connects your `wss://` audio endpoint and a `dial` participant calls the recipient. A repeated `idempotency_key` returns the existing call. Participant creation returns before the person answers, so read the call for `joined_at`, `left_at`, and `ended_at`. Ending a call requests teardown. For inbound calls, Concurrence configures the number routing. See the [voice receiver guide](https://docs.concurrence.com/developer-guide/reference-guides/channel-manager-voice-receiver.md).

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}/participant" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/" method="get" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}" method="delete" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

#### Hold, Mute, and Resume a Participant

`voice:call` updates a connected participant: `hold`, `muted`, and `ends_call_on_exit`. Omitted fields keep their values. A participant that has not joined or has left returns `409`.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}/participant/{participant\_ref}" method="put" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

#### Configure Hold Music

Each voice use case has at most one uploaded track. Without one, holds play default music. Upload MP3 (`audio/mpeg`) or WAV (`audio/wav`, `audio/wave`, `audio/x-wav`) of 10 KiB to 5 MiB in the `hold_music` field with `use-case:write`. An upload replaces the track, and `hold_music_enabled` on the use case shows whether one is set. Neither operation holds or resumes anyone. See [the walkthrough](https://docs.concurrence.com/developer-guide/reference-guides/integrate-channel-manager.md#configure-and-test-hold-music).

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-e31ec9acf0686e51501e8e99759e4099d70b529c%2Fchannel-manager-hold-music.svg?alt=media" alt="An administrator configures a voice use case&#x27;s hold music. During a connected call, the application holds a participant, the configured track plays, and an explicit resume returns the participant to the conference. Configuration alone does not put anyone on hold."><figcaption><p>Configure the track per use case, and control hold and resume per participant.</p></figcaption></figure>

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/use-case/{use\_case\_id}/hold-music" method="put" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/use-case/{use\_case\_id}/hold-music" method="delete" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

#### Transfer or Remove a Participant

A redirect moves a connected leg: `dial` cold-transfers to an approved number, and `farewell` speaks `message` (up to 1000 characters), then hangs up. Test handoffs, including no-answer and disconnect.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}/participant/{participant\_ref}/redirect" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

**Forwarding destinations.** `allowed_forwarding_numbers` holds up to 150 E.164 numbers on a voice use case. It gates operator and transfer participants and dial redirects (`422` otherwise), and an empty list denies them. Callee and media participants are not gated. An inbound voice use case can also set `fallback_forwarding_number`, the E.164 number calls forward to when `inbound_voice_url` fails. A `null` value removes it. The update needs `use-case:write` and the `channel`. A supplied list replaces the old one, and an omitted list is unchanged.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/use-case/{use\_case\_id}" method="put" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

Deleting a participant removes that leg, including a still-ringing destination. It does not end the conference.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}/participant/{participant\_ref}" method="delete" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

#### Fork Incoming Audio

Forks a joined participant's incoming audio in one direction, separate from the two-way `media` participant. Pass per-fork string metadata in `stream_context`, not URL query parameters.

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/voice-call/{call\_ref}/participant/{participant\_ref}/media-stream" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

### Messaging Webhook Secrets

Each messaging use case has a signing secret, returned once at create. Rotation returns a new secret and `old_secret_lasts_until`, with both signatures during the overlap. Changing the receiver URL also issues a secret, without the overlap. Voice use cases do not rotate (`400`). See [Receive Webhooks](https://docs.concurrence.com/pages/TWFPrOxAvAp4FKKfh07v#id-3.-connect-your-inbound-receiver).

{% openapi src="<https://channels.api-us.concurrence.com/openapi.json>" path="/v1/use-case/{use\_case\_id}/webhook-secret" method="post" %}
<https://channels.api-us.concurrence.com/openapi.json>
{% endopenapi %}

## Service Binding

A binding links a provisioned use case to a Concurrence workspace service. Rebinding can select another service in the same workspace but cannot claim a use case bound elsewhere. The standalone API does not need it. See [Use Cases & Bindings](https://docs.concurrence.com/developer-guide/platform-api/workspaces/use-cases.md#service-binding).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/conversations/channel-manager.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
