Integrate Channel Manager Through the API
Connect your application to Channel Manager. Set up access, send messages, handle replies, connect voice, and test the workflow before launch.
Use Channel Manager with your own agent or backend. Your team configures and runs the agent; your application decides whom to contact, what to say, when to follow up, and where to record the result. Channel Manager handles the provisioned channel and its delivery records. You do not need a Concurrence workspace, agent, service, or Developer Console.
This guide covers shared setup, examples for SMS/MMS, email, iMessage, and WhatsApp, and the steps to connect a voice runtime. Start with one approved channel and a recipient your team controls. The Channel Manager reference contains the API contracts and channel requirements.
Example: Follow Up With a Member
Suppose your application needs to contact a member about an approved benefit or service. The same division of work applies to appointment follow-up, support, and other approved programs.
Prepare
Select the member, check permission and timing, and create a workflow ID
Supply the provisioned sender and channel use case
Contact
Compose approved content and call the channel API
Submit the message or connect the call
Continue
Match a reply to the workflow and run your agent
Forward an inbound message, or connect voice audio through the agreed media path
Hand off
Route a request to a specialist and keep the case open until someone accepts it
Connect a specialist to a call when your application requests it
Complete
Record the service outcome in your own system
Retain channel delivery and call records
Save your workflow ID alongside each returned message or call ID. A delivered message is not a completed member request. If the member asks for a specialist, your application owns that handoff and its eventual outcome.
Keep this mapping when changing channels. A follow-up call and an email reply do not automatically become one conversation; your application must link them to the same workflow. Check permission for the new channel before switching.
Before You Start
Request a channel through your Concurrence implementation contact before starting the API steps. Confirm the required sender registrations and provider approvals, then wait for your contact to confirm that the sender and use case are ready. A submitted request is not an approval.
Get these details from your implementation contact:
Deployment
Assigned API host, processing region, retention, and allowed network paths
Channel
Setup ID, use-case ID, approved sender, and the intended message or call flow
Access
Client ID and secret restricted to your setup, with the scopes below
Messaging receiver
Your HTTPS callback URL and its per-use-case signing secret
Test
A controlled recipient, synthetic content, and permission to run the test
Support
Integration and channel-operations contacts who can investigate a failed attempt
Provisioning happens separately from API access. A credential does not create a sender or approve an outreach program. Confirm where content and delivery records will be processed; calling from your own cloud account does not mean the channel service runs there.
For email, test inbound body retrieval before relying on replies. For MMS and other media, test attachment access too. Voice also needs an event receiver and a compatible audio endpoint, described below.
1. Verify Scoped Access
Use the host assigned to your deployment. The current public host is https://channels.api-us.concurrence.com. Keep it in configuration; a change to your website or email domain does not change the API host.
Request only the scopes for the channel you are testing, plus use-case:read:
SMS/MMS
use-case:read sms:read sms:send
use-case:read email:read email:send
iMessage
use-case:read imessage:read imessage:send
use-case:read whatsapp:send
Voice
use-case:read voice:read voice:call
SMS recipient controls need additional grants: sms:consent:read to inspect opt-outs and sms:consent:write to send the registered opt-in message or clear a setup-wide opt-out. Request these only for the client that manages recipient consent, then include the needed scopes when obtaining its token. See SMS recipient opt-in and opt-out.
Load CHANNEL_CLIENT_ID, CHANNEL_CLIENT_SECRET, CHANNEL_SETUP_ID, and CHANNEL_USE_CASE_ID from your approved configuration and secret store. The examples use Bash, cURL, and jq. Keep shell tracing off and tokens out of shared logs.
Set CHANNEL_SCOPES to the row you need. This token example uses SMS:
If a scope is missing, ask the credential owner to correct the grant. Tokens last one hour; obtain another before expiry. Rotating the client secret does not immediately invalidate issued tokens.
2. Confirm the Assigned Route
List your use cases, then read the one you will use:
Check the channel, setup, sender, and callback URL against the handoff from your implementation contact. For phone-based use cases, inspect phone_numbers on the detailed read; the list response can leave it empty. Resolve a wrong sender or receiver before sending.
3. Connect Your Inbound Receiver
SMS, email, iMessage, and WhatsApp send inbound messages to the messaging use case's configured receiver. Your application verifies the event and decides which workflow to resume. Voice uses a separate call-event contract.
Implement these steps in your receiver:
Read the raw request bytes. Verify
X-AMIGO-CHANNEL-MANAGER-WEBHOOK-SIGNATUREas a lowercase hexadecimal HMAC-SHA256, using the provisioned secret as the key. Compare in constant time before processing the JSON.Check the use-case ID against your configuration. Select secrets from that trusted configuration, never from the request. During rotation, handle repeated signature headers, including comma-combined values, and accept a valid signature from an active secret.
Deduplicate on
(use_case_id, idempotency_key). Store the event durably before returning success, then process it asynchronously. A replay must not trigger a second application action.Match the event to your workflow. Use the channel, use case, sender, and any usable parent reference. If several workflows could match, resolve the ambiguity before sending another message.
The public schema describes the messaging inbound-turn envelope. Its authenticated flag concerns channel-origin verification; it does not establish the person's identity or consent.
Match Replies to Your Records
SMS and iMessage
parent_outbound_ref is empty. Look up the workflow using the use case, caller_ref, and your own routing rules.
Read /v1/email/{email_id} using inbound_message_ref. Match the returned in_reply_to_email_id to the CM email id saved from the send. It is null for an unthreaded message.
caller_ref is the recipient's business-scoped address. A recognized reply or reaction target can carry your CM-issued outbound message_id as its parent; otherwise the parent is empty.
Treat an absent parent as a normal case. Do not infer that a reply answers the most recent message if more than one active workflow is possible.
Read Bodies and Attachments
A content part may contain text or a URL. Email bodies are retrieved separately; media on other channels can also require a read. Content URLs are absolute and are issued for the use case's environment and region, so fetch each URL as given rather than rebuilding its host. Verify access from the network where your receiver runs. Use only the agreed content hosts and authentication; never forward a bearer token to an arbitrary callback URL. If you cannot retrieve the content, work with your implementation contact to fix access before enabling that channel.
For delivery status, use the channel's reads described below. The inbound receiver is not a universal delivery-event feed.
4. Send One Controlled Message and Read the Result
Choose one tab. Use that channel's provisioned use case and token scopes, and check the recipient, permission, and content immediately before sending. These messaging examples submit once. If a request times out, reconcile it before trying again.
Set CHANNEL_TEST_RECIPIENT to the controlled phone number and CHANNEL_TEST_MESSAGE to the approved synthetic text.
Before an ordinary send on a supported US long-code or US/Canada toll-free route, use POST /v1/sms/opt-in with use_case_id and to_phone_number to send the registered confirmation. This requires sms:consent:write and prior consent evidence. The confirmation record is per recipient and use case; it does not clear an opt-out. Use the recipient endpoints to inspect suppression and handle re-subscription.
Save the Channel Manager message id with your workflow ID. Read again for later delivery or error information, then have the test recipient reply.
For MMS, the same send accepts media_attachments; add a file part such as --form 'media_attachments=@/path/to/test-image.png' to the request. Test inbound media retrieval separately. See the SMS/MMS contract.
Use a verified sender and a controlled mailbox in CHANNEL_TEST_EMAIL. Set CHANNEL_EMAIL_SUBJECT and CHANNEL_EMAIL_HTML to approved test content. For an unsubscribable use case, the HTML must include both {{ unsubscribe_link }} and {{ unsubscribe_from_all_link }}; the service inserts their URLs. A non-unsubscribable use case must use HTML without template variables.
Save the Channel Manager email id with your workflow ID. Confirm receipt in the mailbox, reply, and verify that your receiver can fetch the inbound body. Read the inbound email using the callback's inbound_message_ref; its in_reply_to_email_id links back to the CM email you sent. To continue that thread, pass the inbound CM ID as reply_to_inbound_email_id on your next send. Test unsubscribe behavior with your channel operator. See the email contract.
Set CHANNEL_TEST_RECIPIENT and CHANNEL_TEST_MESSAGE. Before the first reply, use at most 300 characters with no link, phone number, email address, or media, and respect the six-message limit. Confirm that SMS fallback is acceptable for this program before using the route. See first-reply and suppression rules.
Save the message ID. Check the later delivery/error fields, service, and was_downgraded, then verify a reply reaches the right workflow. Test media access before adding attachments. See the iMessage contract.
Have the test recipient message the provisioned business number first. Set CHANNEL_TEST_BSUID from that event's caller_ref, and set CHANNEL_TEST_MESSAGE to your test reply. The inbound message must be within the last 23 hours for this use case.
Save the message ID and confirm receipt with the test recipient. This route does not send templates or initiate cold outreach. There is no WhatsApp message-read API in the current public schema; ask your channel operator how to investigate delivery or an uncertain send. See the WhatsApp contract.
Connect Voice
Voice needs a working audio integration before the first call. Have your implementation contact confirm the media protocol, event contract, network access, recording settings, and failure behavior. The REST examples below control the call; they do not implement the audio server.
For a controlled outbound test, obtain a token with the voice scopes, select an outbound_voice use case, and set CHANNEL_VOICE_STREAM_URL to your tested wss:// endpoint. Creating the resource does not yet place a call:
Save the returned participant_ref and confirm that your runtime accepts the media connection. Then set CHANNEL_TEST_RECIPIENT to the controlled phone number. The next request dials that number:
Save this participant reference too. A queued participant is not proof that the person answered. Confirm the call state, two-way audio, and the intended agent session. End the test call and read it again to confirm completion:
For an inbound test, call the assigned number and verify that your call-event receiver starts the correct session and attaches the agent's media participant. Test disconnects, no-answer, and any specialist transfer separately. Have the channel operator confirm that each transfer/operator destination is permitted by the deployed use-case forwarding policy; see forwarding destinations. Use call reads to reconcile uncertain participant creation before repeating it. The voice reference explains the available controls and event-contract handoff.
5. Accept the Integration and Hand It Over
Before launch, run these checks on the actual deployment and record the result:
Access
Missing or expired credentials fail. Your client cannot access a designated second test setup.
Send and reply
Correct sender and recipient; saved IDs; reply or call reaches the intended application session.
Receiver
Invalid signatures fail; replay causes one application action; secret rotation preserves reception.
Content and audio
Email bodies and attachments are accessible where needed. Voice has working two-way audio and confirmed teardown.
Opt-out
The selected channel's suppression rules block subsequent sends. Switching senders or channels does not bypass your consent policy.
Uncertain send
A timeout enters investigation rather than triggering an automatic duplicate send or call.
Handoff
A support owner can find the workflow and channel records, investigate a failure, and reach the right escalation contact.
Coordinate suppression tests and cleanup with the channel operator. For supported toll-free SMS, START/UNSTOP clears line-specific opt-out only. Then, after reviewing renewed consent, a client with sms:consent:write can clear setup-wide suppression with a recorded reason. An opt-in-message send record is not proof of consent. See SMS consent controls.
Remove temporary credentials from the test shell:
Keep test and suppression records for the agreed retention period. Use Troubleshooting to raise an issue with the relevant IDs and errors, leaving out credentials and unnecessary message content.
Last updated
Was this helpful?