Create conversation
POST/omnichannel/conversations
Opens a new omnichannel conversation on the specified channel. Use this when receiving an inbound contact via an external adapter or when manually creating a conversation from the agent inbox. The conversation_key field can be supplied by the external system for idempotent creation; if omitted, a random 16-character key is generated.
Request
Request body
Content type application/json (required).
| Field | Type | Required | Description |
|---|---|---|---|
conversation_key | string | No | Optional external reference key. If omitted, a random 16-character key is generated. Max length: 80 |
channel | string | Yes | The channel on which the conversation was initiated. One of: |
subject | string | No | Brief subject line for the conversation. Max length: 255 |
status | string | No | Initial lifecycle status. Defaults to "open". One of: |
priority | string | No | Urgency level. Defaults to "normal". One of: |
assigned_to | integer | No | ID of the agent to assign (must exist in tenant users table). |
channel_profile_id | integer | No | ID of the channel profile to route this conversation through. |
supervisor_user_id | integer | No | ID of the supervising user. |
fallback_channel | string | No | Channel to fall back to if the primary becomes unavailable. One of: |
first_response_due_at | string (date-time) | No | SLA first-response deadline (ISO 8601). |
escalation_at | string (date-time) | No | Auto-escalation trigger timestamp (ISO 8601). |
Example
{
"channel": "email",
"subject": "Billing question - invoice #1042",
"status": "open",
"priority": "high",
"assigned_to": 7,
"channel_profile_id": 3,
"supervisor_user_id": 2,
"fallback_channel": "sms",
"first_response_due_at": "2026-04-08T10:00:00Z",
"escalation_at": "2026-04-08T12:00:00Z"
}Responses
201 Conversation created successfully
Content type application/json, object · OmnichannelConversationV1.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | No | Auto-incremented primary key. |
conversation_key | string | No | Unique external reference key (16 uppercase alphanumeric characters). Max length: 80 |
channel | string | No | The communication channel this conversation was initiated on. One of: |
subject | string, nullable | No | Short description or subject line for the conversation. |
status | string | No | Current lifecycle status of the conversation. One of: |
priority | string | No | Agent urgency priority level. One of: |
quality_status | string | No | AI/supervisor quality assessment of the conversation. One of: |
assigned_to | integer, nullable | No | ID of the agent user currently assigned to this conversation. |
channel_profile_id | integer, nullable | No | ID of the channel profile (queue/routing) this conversation belongs to. |
supervisor_user_id | integer, nullable | No | ID of the supervisor user overseeing this conversation. |
fallback_channel | string, nullable | No | Alternate channel to use if the primary channel becomes unavailable. One of: |
first_response_due_at | string (date-time), nullable | No | SLA deadline for the first agent response. |
escalation_at | string (date-time), nullable | No | Timestamp at which the conversation should be automatically escalated. |
waiting_since_at | string (date-time), nullable | No | Timestamp since the conversation last entered a waiting state. |
created_at | string (date-time) | No | |
updated_at | string (date-time) | No |
422 Validation failed — check channel enum, foreign key IDs, or date formats
Example request
curl -X POST "https://{tenant}.faciotech.net/api/v1/omnichannel/conversations" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"channel": "email", "subject": "Billing question - invoice #1042", "status": "open", "priority": "high", "assigned_to": 7, "channel_profile_id": 3, "supervisor_user_id": 2, "fallback_channel": "sms", "first_response_due_at": "2026-04-08T10:00:00Z", "escalation_at": "2026-04-08T12:00:00Z"}'