SMS
Integrate with provisioned SMS use cases through the workspace conversation lifecycle, with separate consent, suppression, and delivery controls.
Workspace applications use a provisioned SMS use case and the Conversations API to start and continue durable agent conversations. Concurrence manages sender registration, number assignment, provider credentials, and inbound delivery. Contact the Concurrence team to provision a use case before binding it to a service.
Direct sends and recipient controls use separate Channel Manager APIs. Its SMS recipient endpoints support opt-in messaging, opt-out reads, and suppression reversal. They require Channel Manager credentials and scopes; a workspace API key does not grant access. Sender provisioning remains a separate onboarding step.
Bind a Provisioned Use Case
Use Use Cases and Bindings to inspect eligible routing and bind the SMS use case to a service. A binding selects the service configuration; it does not establish carrier approval or recipient consent.
Start an Outbound Conversation
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
HSM execution channel type.
Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.
webPossible values: Destination address for an outbound conversation (E.164 for sms/imessage). Required for non-web.
Channel-manager use case the outbound conversation is sent through. Required for non-web; channel-manager resolves the sender (FROM) from it (never caller-supplied). Must be owned by this workspace.
Optional context steering what the agent opens with on an outbound conversation.
Outbound thread-keyed channels (sms/imessage) only: close any existing ACTIVE conversation on the computed provider thread (recipient + use case) before dispatching, so the opener materializes a brand-new conversation instead of continuing the old thread. Rejected with 422 on channel=web — every web create already starts a new conversation, so force_new is meaningless there.
falseSuccessful Response
HSM execution channel type.
Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.
0True when the conversation recorded more entries than one read takes (10,000), so the turns stop before the end of the conversation.
falseValidation Error
POST /v1/{workspace_id}/conversations HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 271
{
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"channel": "web",
"recipient": "text",
"use_case_id": "123e4567-e89b-12d3-a456-426614174000",
"instruction": "text",
"force_new": false,
"context": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channel_kind": "voice",
"status": "active",
"lifecycle": "active",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"direction": "text",
"turn_count": 0,
"duration_seconds": 1,
"created_at": "text",
"updated_at": "text",
"call_sid": "text",
"caller_id": "text",
"phone_number": "text",
"quality_score": 1,
"has_recording": true,
"completion_reason": "text",
"escalation_status": "text",
"final_state": "text",
"source": "text",
"turns": [
{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": "[Circular Reference]"
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
}
],
"truncated": false,
"plan": "text",
"voice": {
"recording_path": "text",
"twilio_recording_sid": "text",
"twilio_recording_duration": 1,
"has_recording": false,
"emotional_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"barge_in_events": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"states_visited": [
"text"
],
"participants": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"call_analysis": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"forwarding": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"escalation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"quality_breakdown": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"risk_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"latency_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"conversation_metrics": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"tool_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"operator_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}Select the SMS channel and a provisioned use case bound to the service in your workspace. The channel resolves its sender from the provisioned pool. See Starting an Outbound Conversation for the integration workflow.
Conversation creation, the agent's completed turn, provider acceptance, and recipient delivery are separate outcomes. A send rejected by channel policy can leave recorded conversation evidence without a delivered reply. Do not apply one channel-manager error code to every workspace conversation operation.
Inbound Messages and Continuity
Managed inbound delivery validates the provider, resolves the destination use case, and routes ordinary content to the current non-terminal conversation. Phone-based continuity does not itself verify the patient's identity. Recognized consent-management keywords are handled by the channel rather than the agent on the supported sender paths.
Consent and Suppression
Complete the campaign review before outreach. Customer consent evidence must cover the sending brand and intended messages. Concurrence's opt-in-message record reflects provider acceptance of registered confirmation copy, not proof of prior consent or recipient delivery.
Recognized opt-outs suppress ordinary sends across the recipient's managed business setup. Starting another conversation or selecting another number within that setup does not bypass suppression. On the supported toll-free path, START or UNSTOP clears the line-specific opt-out only. After reviewing renewed consent, a caller with Channel Manager's sms:consent:write permission can separately reverse setup suppression with a recorded reason. Workspace credentials alone cannot authorize this reversal.
Registered sender pools also apply content checks to ordinary outbound text. A blocked or unavailable check prevents the send; media handling has different coverage. The full sender, keyword, consent, and registration boundaries are in SMS concepts.
Delivery Evidence
Delivery callbacks can update recorded status after the provider accepts a message. Some carrier paths do not supply final delivery receipts. Inspect the evidence exposed for your deployment rather than treating a completed tool or agent turn as a delivered message.
Last updated
Was this helpful?