Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "escalationId": "esc_9f21",
    "conversationId": "conv_9d2f01",
    "state": "active",
    "messageId": "emsg_4c8a",
    "seq": 1,
    "delivered": true
  }
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Escalation

Initiate an outbound escalation (harness-started SMS thread)

Open a BRAND-NEW SMS conversation with a customer and send its first message, with the thread owned by the calling connector from the first instant. This is the outbound-initiated sibling of the inbound escalation path: once the session exists the customer’s replies route to your harness automatically (the AI does not answer them), so you continue on POST /escalations//messages exactly as you would on any escalation you claimed. The session is created ALREADY CLAIMED by the calling key and active — you do not race a claim SLA on a thread you started. COMPLIANCE (all enforced server-side, none of it optional):

There is no from field. The sending number is derived from the agent’s SMS-active number; an agent with none returns 422 no_sms_number.
to must be a US or Canada (+1) number. The platform’s numbers and its A2P 10DLC/TCR registration are North American, so any other destination is refused 422 unsupported_country — nothing is sent.
Volume is capped per workspace: a rolling 24-hour ceiling on how many conversations a harness may START (200 by default). Past it, 429 daily_initiate_cap carries details.nextOpen and Retry-After. An idempotent replay is answered from the original receipt and is never capped.
The recipient must have a recorded consent basis — conversational (a customer who texted you first) or express (captured in a call or chat). Otherwise 422 consent_required. Orgs that hold consent out-of-band can be granted a bypass, which is recorded in the compliance trail.
The first text is business-initiated, so it is quiet-hours gated and carries the required brand + “Msg & data rates may apply. Reply HELP for help, STOP to opt out.” disclosure block, appended by the platform. Do not add your own.
An initiate that did NOT send is always an explicit error, never a 200 with delivered:false. A quiet-hours refusal is 409 quiet_hours and carries details.nextOpen — retry after it. IDEMPOTENCY. The key is (organization, client_message_id) — durable and stable, so a replay returns the original receipt (byte for byte) and never sends a second text: after the original escalation was resolved, after the 72-hour conversation-episode rollover, and against a concurrent duplicate of itself. Reusing an id for a DIFFERENT message is 409 client_message_id_reused. WHEN THE OUTCOME IS UNKNOWN. If the carrier request fails in a way that does not prove the message stayed home (a timeout, a transport failure, a 5xx), the answer is 409 send_state_unknown carrying details.escalationId and details.conversationId. It is the ONLY refusal here that does not promise the recipient’s phone stayed silent, so do not blindly retry: read the thread, or replay the SAME client_message_id — a replay resolves to the same answer, or to the receipt once the state settles, and never sends a second text. Requires the deployment to have the Agent Bridge enabled (503 bridge_disabled), the org to be enabled for harness-initiated conversations (403 harness_outbound_disabled) and on a Starter plan or higher (403 plan_required).

POST

escalations

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "escalationId": "esc_9f21",
    "conversationId": "conv_9d2f01",
    "state": "active",
    "messageId": "emsg_4c8a",
    "seq": 1,
    "delivered": true
  }
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Flowyte secret API key (Authorization: Bearer flowyte_sk_live_…). Scope-gated; is scoped to your organization — a key can never reach another tenant. The listed scopes in each operation's apiKey requirement are the scopes that key must hold. The tokenUrl is nominal: keys are minted in the dashboard.

Body

application/json

A harness-initiated outbound SMS thread. NOTE the absence of a from field: the sending number is derived server-side from the agent's SMS-active number, because an agent structurally cannot text without an assigned number.

agentId

string

required

The agent whose SMS-active number the thread is opened on (and whose conversation history it joins).

destinationId

string

required

The escalation destination that will own the conversation. Must be status 'active', allow the sms channel, and belong to a CONNECTED AI Harness integration.

string

required

The recipient in E.164. Must have a recorded consent basis (conversational or express) unless the org holds a consent bypass.

Example:

"+14155551234"

text

string

required

The first message. Send the message ONLY — the platform appends the required brand prefix and the "Msg & data rates may apply. Reply HELP for help, STOP to opt out." disclosure block, sanitizes to GSM-7 and applies the 2-segment cap.

client_message_id

string

required

Idempotency key — a replay returns the original receipt and never sends a second text.

channel

enum<string>

default:sms

Only sms can be initiated outbound — chat has no visitor to push to until one arrives.

Available options:

sms

Response

The conversation was opened and the first message sent (also returned on an idempotent replay).

success

boolean

required

data

object

required

Show child attributes

message

string

errors

object[]

Show child attributes

Using the API

Endpoints

Initiate an outbound escalation (harness-started SMS thread)

Authorizations

Body

Response