HCC Docs

Calls

List calls, newest first

GET /v1/calls calls:read

Calls in this API key's environment. Every filter is optional; they combine with AND. The cursor pages through the same filters.

Query

  • limit integer
  • cursor string
  • from string

    Calls started at or after this time, ISO 8601

  • to string

    Calls started before this time, ISO 8601

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • status one of several

    Any of these statuses (queued, ringing, in_progress, completed, busy, no_answer, failed, canceled): repeat the parameter, use status[], or separate with commas

  • number string

    The from or to number: an E.164 prefix (+1415), or digits that start the number after its + or end it (0100). Spaces, dashes and brackets are ignored

  • repId string

    Calls the rep (rep_…) placed, answered from a queue, or recorded the disposition of

  • queue string

    Calls that visited this queue, by name

  • disposition string

    Calls with this disposition

  • flow string

    Calls that ran this call flow, by name

  • simulated "true" | "false"

    true: only calls on the simulated carrier (test mode); false: only real ones

Responses

  • 200

    A page of calls

    Fields
    • data Call[] required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • from string required
      • to string required
      • phoneNumberId string | null required
      • agentId string | null required
      • environment "live" | "test" required

        test calls run on the simulated carrier and never reach a phone

      • startedAt string | null required
      • answeredAt string | null required
      • endedAt string | null required
      • durationSeconds integer | null required
      • flow string | null required

        The call flow this call runs, if any

      • flowVersion string | null required

        The flow version the call started with

      • disposition string | null required

        Set by the flow's hangup({ disposition }), or a rep's wrap-up

      • repId string | null required

        A rep outbound call: the rep it was placed for

      • context any

        A rep outbound call: its context

      • outcome "completed" | "rep_unavailable" | "busy" | "no_answer" | "failed" | "cancelled" | "voicemail_left" | null required

        How a rep outbound call ended: completed, rep_unavailable (the rep never answered, the customer was not dialed), busy, no_answer, failed or cancelled. On a campaign's call: voicemail_left, when onVoicemail left a message on a machine

    • nextCursor string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Place an outbound call

POST /v1/calls calls:write

Every call is checked before anything rings, and audited. A number on the Do Not Call list is a 422 do_not_call. Without repId, a call outside 8:00 to 21:00 in the time zone of the number's lead, or else the timezone you give, is a 422 outside_calling_hours. With neither zone the call is placed, and audited as not checked.

Headers

  • Idempotency-Key string

    Makes the request safe to retry. For 24h, a request with the same key and body replays the stored response (with Idempotent-Replayed: true); the same key with a different request is a 422 idempotency_key_reused, and while the first request is still running a 409 idempotency_key_in_use. Server errors, 409s and 429s are not stored.

Body

  • from string

    One of the tenant numbers. Required, except with repId: then it defaults to the rep's caller ID, the workspace's, or the first number.

  • to string required
  • recording false

    false: this call is not recorded, whatever the recording policy says. It can only turn recording off.

  • timezone string

    The callee's IANA time zone, for the calling hours check (8:00 to 21:00). Used when no lead with this number has one: a lead's zone comes first. With neither the call is placed, and audited as not checked. Not with repId.

  • instructions object[]

    Call Instructions to run once the call is answered. Give this or agentId.

    Fields
    say
    • type "say" required
    • text string required
    • voice string
    • language string
    play
    • type "play" required
    • url string required
    • loop integer

      1 to 100.

    pause
    • type "pause" required
    • seconds integer required

      1 to 60.

    connectAgent
    • type "connectAgent" required
    • agentId string required
    • provider string
    • variables object
    dial
    • type "dial" required
    • to string required
    • callerId string
    • timeoutSeconds integer

      5 to 600.

    • record boolean
    enqueue
    • type "enqueue" required
    • queue string required
    gather
    • type "gather" required
    • input "dtmf" | "speech"[] required
    • numDigits integer

      1 to 32.

    • timeoutSeconds integer

      1 to 60.

    • prompt object
      Fields
      • type "say" required
      • text string required
      • voice string
      • language string
    • tag string
    • sensitive boolean
    record
    • type "record" required
    • maxLengthSeconds integer

      1 to 14400.

    hangup
    • type "hangup" required
    • disposition string
    • callbackAt integer
  • agentId string

    Shorthand for instructions: [{ type: "connectAgent", agentId, variables }]: our agt_… id or the platform agent id. Give this or instructions.

  • variables object

    Dynamic variables for the agent; only with agentId.

  • flow string

    Run this registered call flow: its handlers drive the call. Give this, instructions or agentId. The API key picks the environment (live or test).

  • input object

    The flow's input, checked against the schema it registered; only with flow.

  • repId string

    Place the call for this rep (click-to-call): the rep's softphone rings first, and the customer is dialed once they answer. Not with instructions, agentId or flow. Refusals: 409 rep_busy / rep_offline, 422 caller_id_not_owned, no_caller_id, do_not_call, 409 conflict (no softphone).

  • context any

    With repId: up to 4 KB of JSON kept on the call and its events.

Responses

  • 201

    Call created

    Fields
    • data Call required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • from string required
      • to string required
      • phoneNumberId string | null required
      • agentId string | null required
      • environment "live" | "test" required

        test calls run on the simulated carrier and never reach a phone

      • startedAt string | null required
      • answeredAt string | null required
      • endedAt string | null required
      • durationSeconds integer | null required
      • flow string | null required

        The call flow this call runs, if any

      • flowVersion string | null required

        The flow version the call started with

      • disposition string | null required

        Set by the flow's hangup({ disposition }), or a rep's wrap-up

      • repId string | null required

        A rep outbound call: the rep it was placed for

      • context any

        A rep outbound call: its context

      • outcome "completed" | "rep_unavailable" | "busy" | "no_answer" | "failed" | "cancelled" | "voicemail_left" | null required

        How a rep outbound call ended: completed, rep_unavailable (the rep never answered, the customer was not dialed), busy, no_answer, failed or cancelled. On a campaign's call: voicemail_left, when onVoicemail left a message on a machine

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    idempotency_key_in_use: a request with this key is still running

  • 422

    The connectAgent target is disabled or removed, or idempotency_key_reused

  • 429

    rate_limited, or another limit named by error.code

Get a call

GET /v1/calls/{id} calls:read

Path

  • id string required

Responses

  • 200

    The call

    Fields
    • data Call required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • from string required
      • to string required
      • phoneNumberId string | null required
      • agentId string | null required
      • environment "live" | "test" required

        test calls run on the simulated carrier and never reach a phone

      • startedAt string | null required
      • answeredAt string | null required
      • endedAt string | null required
      • durationSeconds integer | null required
      • flow string | null required

        The call flow this call runs, if any

      • flowVersion string | null required

        The flow version the call started with

      • disposition string | null required

        Set by the flow's hangup({ disposition }), or a rep's wrap-up

      • repId string | null required

        A rep outbound call: the rep it was placed for

      • context any

        A rep outbound call: its context

      • outcome "completed" | "rep_unavailable" | "busy" | "no_answer" | "failed" | "cancelled" | "voicemail_left" | null required

        How a rep outbound call ended: completed, rep_unavailable (the rep never answered, the customer was not dialed), busy, no_answer, failed or cancelled. On a campaign's call: voicemail_left, when onVoicemail left a message on a machine

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Hang up a live call

POST /v1/calls/{id}/hangup calls:write

Path

  • id string required

Headers

  • Idempotency-Key string

    Makes the request safe to retry. For 24h, a request with the same key and body replays the stored response (with Idempotent-Replayed: true); the same key with a different request is a 422 idempotency_key_reused, and while the first request is still running a 409 idempotency_key_in_use. Server errors, 409s and 429s are not stored.

Responses

  • 200

    Hangup requested

    Fields
    • data Call required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • from string required
      • to string required
      • phoneNumberId string | null required
      • agentId string | null required
      • environment "live" | "test" required

        test calls run on the simulated carrier and never reach a phone

      • startedAt string | null required
      • answeredAt string | null required
      • endedAt string | null required
      • durationSeconds integer | null required
      • flow string | null required

        The call flow this call runs, if any

      • flowVersion string | null required

        The flow version the call started with

      • disposition string | null required

        Set by the flow's hangup({ disposition }), or a rep's wrap-up

      • repId string | null required

        A rep outbound call: the rep it was placed for

      • context any

        A rep outbound call: its context

      • outcome "completed" | "rep_unavailable" | "busy" | "no_answer" | "failed" | "cancelled" | "voicemail_left" | null required

        How a rep outbound call ended: completed, rep_unavailable (the rep never answered, the customer was not dialed), busy, no_answer, failed or cancelled. On a campaign's call: voicemail_left, when onVoicemail left a message on a machine

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    idempotency_key_in_use: a request with this key is still running

  • 422

    idempotency_key_reused: this key was used with a different request

  • 429

    rate_limited, or another limit named by error.code

Replace the instructions of a live call

POST /v1/calls/{id}/instructions calls:write

Path

  • id string required

Headers

  • Idempotency-Key string

    Makes the request safe to retry. For 24h, a request with the same key and body replays the stored response (with Idempotent-Replayed: true); the same key with a different request is a 422 idempotency_key_reused, and while the first request is still running a 409 idempotency_key_in_use. Server errors, 409s and 429s are not stored.

Body

  • instructions object[] required
    Fields
    say
    • type "say" required
    • text string required
    • voice string
    • language string
    play
    • type "play" required
    • url string required
    • loop integer

      1 to 100.

    pause
    • type "pause" required
    • seconds integer required

      1 to 60.

    connectAgent
    • type "connectAgent" required
    • agentId string required
    • provider string
    • variables object
    dial
    • type "dial" required
    • to string required
    • callerId string
    • timeoutSeconds integer

      5 to 600.

    • record boolean
    enqueue
    • type "enqueue" required
    • queue string required
    gather
    • type "gather" required
    • input "dtmf" | "speech"[] required
    • numDigits integer

      1 to 32.

    • timeoutSeconds integer

      1 to 60.

    • prompt object
      Fields
      • type "say" required
      • text string required
      • voice string
      • language string
    • tag string
    • sensitive boolean
    record
    • type "record" required
    • maxLengthSeconds integer

      1 to 14400.

    hangup
    • type "hangup" required
    • disposition string
    • callbackAt integer

Responses

  • 200

    Call redirected

    Fields
    • data Call required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • from string required
      • to string required
      • phoneNumberId string | null required
      • agentId string | null required
      • environment "live" | "test" required

        test calls run on the simulated carrier and never reach a phone

      • startedAt string | null required
      • answeredAt string | null required
      • endedAt string | null required
      • durationSeconds integer | null required
      • flow string | null required

        The call flow this call runs, if any

      • flowVersion string | null required

        The flow version the call started with

      • disposition string | null required

        Set by the flow's hangup({ disposition }), or a rep's wrap-up

      • repId string | null required

        A rep outbound call: the rep it was placed for

      • context any

        A rep outbound call: its context

      • outcome "completed" | "rep_unavailable" | "busy" | "no_answer" | "failed" | "cancelled" | "voicemail_left" | null required

        How a rep outbound call ended: completed, rep_unavailable (the rep never answered, the customer was not dialed), busy, no_answer, failed or cancelled. On a campaign's call: voicemail_left, when onVoicemail left a message on a machine

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    idempotency_key_in_use: a request with this key is still running

  • 422

    The connectAgent target is disabled or removed, or idempotency_key_reused

  • 429

    rate_limited, or another limit named by error.code

Say what a rep is told of the AI agent's conversation

POST /v1/calls/{id}/ai-summary calls:write

Shown on the offer, the call and the wrap-up, from the answer on: a desk that has the call fills in. A flow's outbound call has no session until it's answered, and before that this is refused (409). It beats the agent platform's own summary. For agents with no post-call report, such as SIP, this and aiSummary on a transfer are the only way one gets to a rep.

Path

  • id string required

Body

  • text string required

    What the rep is told of the AI agent's conversation. Cut to 2 KB.

Responses

  • 200

    Set

    Fields
    • data AiSummarySet required
      Fields
      • applied boolean required

        Whether this is now what reps see. Blank text changes nothing.

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Send a custom event to a live call's flow

POST /v1/calls/{id}/events calls:write

Delivers { name, payload } to the call flow's .on(name) handler, synchronously within the flow's timeout. Actions the handler returns are applied to the call.

Path

  • id string required

Headers

  • Idempotency-Key string

    Makes the request safe to retry. For 24h, a request with the same key and body replays the stored response (with Idempotent-Replayed: true); the same key with a different request is a 422 idempotency_key_reused, and while the first request is still running a 409 idempotency_key_in_use. Server errors, 409s and 429s are not stored.

Body

  • name string required
  • payload any

Responses

  • 202

    Delivered

    Fields
    • data EmittedCallEvent required
      Fields
      • id string required

        The flow event id (stable across our retries)

      • applied boolean required

        Whether the handler returned actions we applied

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    The call has no flow or has ended

  • 429

    rate_limited, or another limit named by error.code

Start a consult: the customer goes on hold while the target rings

POST /v1/calls/{id}/consults calls:write

repId must be a Rep on the call (409 otherwise). A queue must be registered (404), and a number on the Do Not Call list is refused (409). While a consult is live, a second consult, a transfer, hold, keypad tones and a supervisor taking over are refused (409).

Path

  • id string required

Body

  • repId string required

    The Rep on the call who is consulting

  • target object required
    Fields
    rep
    • type "rep" required
    • repId string required
    queue
    • type "queue" required
    • queue string required
    number
    • type "number" required
    • to string required

Responses

  • 201

    The consult

    Fields
    • data Consult required

      A Rep's consult on a call: the customer is on hold while the Rep talks to a Rep, queue or number, then hands over (complete), comes back (cancel) or brings everyone together (merge).

      Fields
      • id string required
      • callId string required
      • status "dialing" | "consulting" | "merged" | "ended" required
      • target object required
      • repId string required
      • targetRepId string | null required
      • transferId string | null required
      • outcome "completed" | "canceled" | "target_failed" | "target_left" | "caller_left" | null required
      • reason "busy" | "no_answer" | "failed" | "unavailable" | "queue_overflow" | "queue_closed" | "queue_outside_hours" | "rep_unavailable" | null required
      • startedAt string required
      • connectedAt string | null required
      • mergedAt string | null required
      • endedAt string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    The call or consult is not in a state to do this

  • 429

    rate_limited, or another limit named by error.code

Read a consult

GET /v1/consults/{id} calls:read

Path

  • id string required

Responses

  • 200

    The consult

    Fields
    • data Consult required

      A Rep's consult on a call: the customer is on hold while the Rep talks to a Rep, queue or number, then hands over (complete), comes back (cancel) or brings everyone together (merge).

      Fields
      • id string required
      • callId string required
      • status "dialing" | "consulting" | "merged" | "ended" required
      • target object required
      • repId string required
      • targetRepId string | null required
      • transferId string | null required
      • outcome "completed" | "canceled" | "target_failed" | "target_left" | "caller_left" | null required
      • reason "busy" | "no_answer" | "failed" | "unavailable" | "queue_overflow" | "queue_closed" | "queue_outside_hours" | "rep_unavailable" | null required
      • startedAt string required
      • connectedAt string | null required
      • mergedAt string | null required
      • endedAt string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Hand over: the customer comes off hold, then the Rep leaves

POST /v1/consults/{id}/complete calls:write

Path

  • id string required

Responses

  • 200

    The consult

    Fields
    • data Consult required

      A Rep's consult on a call: the customer is on hold while the Rep talks to a Rep, queue or number, then hands over (complete), comes back (cancel) or brings everyone together (merge).

      Fields
      • id string required
      • callId string required
      • status "dialing" | "consulting" | "merged" | "ended" required
      • target object required
      • repId string required
      • targetRepId string | null required
      • transferId string | null required
      • outcome "completed" | "canceled" | "target_failed" | "target_left" | "caller_left" | null required
      • reason "busy" | "no_answer" | "failed" | "unavailable" | "queue_overflow" | "queue_closed" | "queue_outside_hours" | "rep_unavailable" | null required
      • startedAt string required
      • connectedAt string | null required
      • mergedAt string | null required
      • endedAt string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    The call or consult is not in a state to do this

  • 429

    rate_limited, or another limit named by error.code

Back to the caller: the target leaves, the customer comes off hold

POST /v1/consults/{id}/cancel calls:write

Path

  • id string required

Responses

  • 200

    The consult

    Fields
    • data Consult required

      A Rep's consult on a call: the customer is on hold while the Rep talks to a Rep, queue or number, then hands over (complete), comes back (cancel) or brings everyone together (merge).

      Fields
      • id string required
      • callId string required
      • status "dialing" | "consulting" | "merged" | "ended" required
      • target object required
      • repId string required
      • targetRepId string | null required
      • transferId string | null required
      • outcome "completed" | "canceled" | "target_failed" | "target_left" | "caller_left" | null required
      • reason "busy" | "no_answer" | "failed" | "unavailable" | "queue_overflow" | "queue_closed" | "queue_outside_hours" | "rep_unavailable" | null required
      • startedAt string required
      • connectedAt string | null required
      • mergedAt string | null required
      • endedAt string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    The call or consult is not in a state to do this

  • 429

    rate_limited, or another limit named by error.code

Bring everyone together: the customer comes off hold, and nobody leaves

POST /v1/consults/{id}/merge calls:write

Path

  • id string required

Responses

  • 200

    The consult

    Fields
    • data Consult required

      A Rep's consult on a call: the customer is on hold while the Rep talks to a Rep, queue or number, then hands over (complete), comes back (cancel) or brings everyone together (merge).

      Fields
      • id string required
      • callId string required
      • status "dialing" | "consulting" | "merged" | "ended" required
      • target object required
      • repId string required
      • targetRepId string | null required
      • transferId string | null required
      • outcome "completed" | "canceled" | "target_failed" | "target_left" | "caller_left" | null required
      • reason "busy" | "no_answer" | "failed" | "unavailable" | "queue_overflow" | "queue_closed" | "queue_outside_hours" | "rep_unavailable" | null required
      • startedAt string required
      • connectedAt string | null required
      • mergedAt string | null required
      • endedAt string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 409

    The call or consult is not in a state to do this

  • 429

    rate_limited, or another limit named by error.code