HCC Docs

Reps

List reps, newest first

GET /v1/reps reps:read

Query

  • limit integer
  • cursor string

Responses

  • 200

    A page of reps

    Fields
    • data Rep[] required
      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
    • 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

Get a rep

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

Path

  • id string required

Responses

  • 200

    The rep

    Fields
    • data Rep required

      A human who takes calls: a workspace member enabled as a rep in the dashboard, with skills and a live state. Routing sets on_call and wrap_up.

      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Update a rep's skills, caller ID or device, or enable / disable them

PATCH /v1/reps/{id} reps:write

A disabled rep goes offline and is offered no calls. Skills, enabled and the caller ID also apply to live calls, so they need a live key; a test key can only change device, and not on a phone verified with a real call.

Path

  • id string required

Body

  • skills object
  • enabled boolean
  • defaultCallerId string | null

    One of the tenant numbers, or null for the workspace default

  • device "softphone" | "phone"

    phone needs a verified phone (409 otherwise)

Responses

  • 200

    The updated rep

    Fields
    • data Rep required

      A human who takes calls: a workspace member enabled as a rep in the dashboard, with skills and a live state. Routing sets on_call and wrap_up.

      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A test key (live_mode_only): this change needs a live API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Set a rep's state: available, away or offline

PUT /v1/reps/{id}/state reps:write

Refused (409) while the rep is on a call. Leaving wrap_up this way ends it.

Path

  • id string required

Body

  • state "available" | "away" | "offline" required
  • reason string | null

    For away

Responses

  • 200

    The rep

    Fields
    • data Rep required

      A human who takes calls: a workspace member enabled as a rep in the dashboard, with skills and a live state. Routing sets on_call and wrap_up.

      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Register a rep's own phone and call it with a verification code

PUT /v1/reps/{id}/phone reps:write

Replaces any phone the rep had (it is unverified again, and device goes back to softphone). We call the number and read a 6-digit code, valid for 10 minutes; at most 5 calls an hour (429 after). With a test key the call runs on the simulator, whose timeline shows the code, and the phone then only rings simulated calls. A test key can not replace a phone verified with a real call.

Path

  • id string required

Body

  • e164 string required
  • label string | null

Responses

  • 202

    The verification call was placed

    Fields
    • data RepPhoneVerification required
      Fields
      • verificationId string required
      • expiresAt string required
      • environment "live" | "test" required

        Test keys place the verification call on the simulator

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A test key (live_mode_only): this change needs a live API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Remove a rep's own phone

DELETE /v1/reps/{id}/phone reps:write

Calls ring the softphone again (device goes back to softphone). A test key can not remove a phone verified with a real call.

Path

  • id string required

Responses

  • 200

    The rep

    Fields
    • data Rep required

      A human who takes calls: a workspace member enabled as a rep in the dashboard, with skills and a live state. Routing sets on_call and wrap_up.

      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A test key (live_mode_only): this change needs a live API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Verify a rep's phone with the code the call read out

POST /v1/reps/{id}/phone/verify reps:write

Emits rep.phone.verified. 422 invalid_code, code_expired or too_many_attempts (5 wrong codes) otherwise; the last two need a new call (PUT /v1/reps/{id}/phone).

Path

  • id string required

Body

  • code string required

Responses

  • 200

    The rep

    Fields
    • data Rep required

      A human who takes calls: a workspace member enabled as a rep in the dashboard, with skills and a live state. Routing sets on_call and wrap_up.

      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Record the disposition of a rep's call and end their wrap-up

PUT /v1/reps/{id}/wrap-up reps:write

What the desk does when the rep picks a disposition, for reps who take calls on their own phone without the desk open. A disposition in the workspace's DNC list adds the other party to Do Not Call. 409 unless it is the rep's current or last call.

Path

  • id string required

Body

  • callId string required
  • disposition string required
  • notes string

Responses

  • 200

    The rep

    Fields
    • data Rep required

      A human who takes calls: a workspace member enabled as a rep in the dashboard, with skills and a live state. Routing sets on_call and wrap_up.

      Fields
      • id string required
      • userId string required
      • name string required
      • email string required
      • enabled boolean required
      • skills object required

        Skill name → level 1-10

      • maxConcurrentCalls integer required
      • defaultCallerId string | null required

        The caller ID of the rep's outbound calls when none is given

      • device "softphone" | "phone" required

        Where calls ring: the browser softphone, or the rep's own verified phone (call screening: they press 1 to take each call)

      • phone RepPhone required

        The rep's own phone, if registered

      • state "offline" | "available" | "on_call" | "wrap_up" | "away" required
      • reason string | null required

        Why the rep is away, e.g. lunch

      • stateSince string required
      • callId string | null required

        The call the rep is on, if any

      • createdAt string required
      • updatedAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code