HCC Docs

Translation

The environment's live translation policy, and the stop switch

GET /v1/translation-policy flows:read

Responses

  • 200

    Status

    Fields
    • data TranslationPolicyStatus required
      Fields
      • policy any required
      • suspendedAt string | null required

        When the workspace's stop switch was set; nothing is translated while it is on

      • suspendedBy 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

Register the live translation policy

PUT /v1/translation-policy flows:write

Like PUT /v1/recording-policy: hcc.serve reports it on startup (mode: "report" only activates a version never seen before) and hcc.translation.deploy activates it from CI. A call keeps the version it started with. A redeploy does not clear the workspace's stop switch.

Body

  • policy object required
    Fields
    • provider "platform" | object

      Default "platform".

      Fields
      object
      • integration string required
    • voice "none" | "rep" | "customer" | "both"

      Default "none".

    • notice object

      Default {}.

      Fields
      • text string

        Default "This call uses automated translation.".

      • voice string
      • language string
    • repMayStart boolean

      Default false.

    • autoStart false | "language_differs" | object

      Default false.

      Fields
      object
      • when "language_differs" required
      • voice "never" | "known_only"

        Default "never".

    • detectLanguage boolean

      Default false.

    • keepTranscript boolean

      Default false.

    • maxMinutesPerCall integer

      Default 120. 1 to 240.

  • mode "report" | "deploy"

    Default "report".

  • alsoTest boolean

    Live keys only: also register the same version in test Default false.

Responses

  • 200

    The registered version

    Fields
    • data TranslationPolicy required

      What defineTranslationPolicy declares. No call is translated unless one is deployed.

      Fields
      • version string required
      • environment "live" | "test" required
      • definition object required
      • createdAt string required
      • activatedAt string required
      • lastSeenAt string required
    • test object

      With alsoTest: the version registered in test

      Fields
      • data TranslationPolicy required

        What defineTranslationPolicy declares. No call is translated unless one is deployed.

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Translate a call

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

Plays the policy’s notice to the customer, then translates between them and the rep. Answers once the notice is playing; call.translation.started or call.translation.failed follows. A refusal is a 409 whose details.reason says why: not_configured, not_allowed, no_rep, language_unsupported, unavailable_on_carrier, suspended. Starting one that runs already answers it.

Path

  • id string required

Body

  • customer string

    The customer's language. Else what the call knows (a queue's, a lead's)

  • rep string

    The rep's. Else their profile's

  • voice "none" | "rep" | "customer" | "both"

    Who hears it spoken: none (captions only), rep, customer or both. At most what the policy allows. Default: the policy's

Responses

  • 202

    Starting

    Fields
    • data CallTranslation required

      starting: the customer is hearing the notice. call.translation.started says when it runs.

      Fields
      • id string required
      • status "starting" | "running" | "stopped" required
      • customerLanguage string required
      • repLanguage string required
      • repId string required
      • voice "none" | "rep" | "customer" | "both" required
      • startedBy "code" | "rep" | "auto" required
      • startedAt string | null required
      • stopReason "requested" | "rep_left" | "call_ended" | "languages_match" | "limit" | "billing" | "suspended" | "provider_error" | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Stop translating a call

DELETE /v1/calls/{id}/translation calls:write

call.translation.stopped follows with the minutes billed. Your code may start it again; a rep who turns it off on the Desk keeps it off for the call.

Path

  • id string required

Responses

  • 202

    Stopping, or nothing ran

    Fields
    • data any required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

A call's translations

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

Each stretch of live translation on the call, oldest first. With the policy’s keepTranscript, its final lines in both languages, kept under the recording policy’s transcript retention (365 days without one). Events never carry the text.

Path

  • id string required

Responses

  • 200

    Translations

    Fields
    • data CallTranslationStretch[] required
      Fields
      • id string required
      • customerLanguage string | null required
      • repLanguage string | null required
      • repId string | null required
      • voice "none" | "rep" | "customer" | "both" required
      • startedBy "code" | "rep" | "auto" | null required
      • startedAt string required
      • endedAt string | null required

        Null while it runs

      • stopReason "requested" | "rep_left" | "call_ended" | "languages_match" | "limit" | "billing" | "suspended" | "provider_error" | null required
      • billedMinutes integer required
      • transcript "none" | "kept" | "deleted" required

        none: the policy had no keepTranscript. kept: the lines are here until deleteAfter. deleted: retention or a delete on request took them.

      • deleteAfter string | null required
      • lines object[] required

        The final lines, in order. Empty unless transcript is kept.

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Clear the workspace's translation stop switch

DELETE /v1/translation-policy/suspension translation:manage

The dashboard can only stop translation. Starting it again is this deliberate call, with a live key that has the translation:manage scope, which only an owner or admin can grant. New calls follow the policy again; calls already in progress keep none.

Responses

  • 204

    Cleared

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

TermsPrivacy