Create a client token

POST

/client_tokens

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const clientToken = await mv.clientTokens.create({
  assistant_id: "asst_8tRPaZp5hLMbrGqdJ9AmNa",
  metadata: {
    crm_contact_id: "0031x00000AbCdE",
  },
  origin: "https://shop.example",
  ttl_s: 300,
});
console.log(clientToken);

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

client_token = client.client_tokens.create({
    "assistant_id": "asst_8tRPaZp5hLMbrGqdJ9AmNa",
    "metadata": {
        "crm_contact_id": "0031x00000AbCdE",
    },
    "origin": "https://shop.example",
    "ttl_s": 300,
})
print(client_token)

curl -X POST https://api.morevoice.ai/v1/client_tokens \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "assistant_id": "asst_8tRPaZp5hLMbrGqdJ9AmNa",
  "metadata": {
    "crm_contact_id": "0031x00000AbCdE"
  },
  "origin": "https://shop.example",
  "ttl_s": 300
}'

Mint, on your server, a short-lived token a browser uses to start one call to one assistant with @morevoice/web (MoreVoiceWeb.start({ token })). The token works once, until expires_at; bind it to your site with origin. It carries the call’s ID, so you can follow the call (webhooks, GET /v1/calls/{id}/events) before it starts.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Idempotency-Key

string

>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example

5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body

application/json

What the token opens: one call to one assistant (or one agent softphone).

object

agent_user_id

The agent whose softphone the token opens (the embeddable softphone; /ws/call refuses agent tokens).

string

<= 200 characters /^usr_[0-9A-Za-z]+$/

assistant_id

The assistant the browser will talk to.

string

<= 200 characters /^asst_[0-9A-Za-z]+$/

metadata

Stored on the call (metadata), as on POST /v1/calls.

object

<= 50 properties

key

additional properties

string

<= 500 characters

origin

The only website the token works from (https://shop.example): the browser’s Origin must match. Strongly recommended. http is accepted for localhost only.

string

<= 300 characters /^(https:\/\/[^/\s?#]+|http:\/\/(localhost|127\.0\.0\.1)(:\d{1,5})?)\/?$/

ttl_s

How long the token can be used to start the call, in seconds (300–900, default 300). The call itself may run longer.

integer

default: 300 >= 300 <= 900

Example

{
  "assistant_id": "asst_8tRPaZp5hLMbrGqdJ9AmNa",
  "metadata": {
    "crm_contact_id": "0031x00000AbCdE"
  },
  "origin": "https://shop.example",
  "ttl_s": 300
}

Responses

201

The token.

application/json

A short-lived, single-use token a browser uses to start one call (the @morevoice/web SDK takes it as token). Mint it on your server: it keeps your secret key off the page.

object

agent_user_id

required

Any of:

string
null

A user ID (prefix usr_).

string

/^usr_[0-9A-Za-z]+$/

assistant_id

required

Any of:

string
null

A assistant ID (prefix asst_).

string

/^asst_[0-9A-Za-z]+$/

call_id

required

The call the token opens (the same ID the call will have).

string

/^call_[0-9A-Za-z]+$/

expires_at

required

An ISO-8601 timestamp in UTC.

string format: date-time

livemode

required

true in live mode, false in test mode.

boolean

object

required

string

Allowed value: client_token

origin

required

The website the token is bound to, or null.

string | null

token

required

The client token (a signed JWT). Give it to the browser; it opens one call, once, before expires_at.

string

ws_url

required

Where the browser connects: <ws_url>?client_token=<token> (the @morevoice/web SDK does it for you).

string

Example

{
  "agent_user_id": null,
  "assistant_id": "asst_8tRPaZp5hLMbrGqdJ9AmNa",
  "call_id": "call_3slqGaD2htUzxdRsI",
  "expires_at": "2026-11-03T09:19:22.000Z",
  "livemode": true,
  "object": "client_token",
  "origin": "https://shop.example",
  "token": "<client_token: short-lived JWT, pass it through unchanged>",
  "ws_url": "wss://api.morevoice.ai/ws/call"
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

409

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.