Skip to content
MoreVoiceDevelopers

Update a copilot profile

PATCH
/copilot_profiles/{id}
import MoreVoice from "@morevoice/sdk";


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


const copilotProfile = await mv.copilotProfiles.update("cop_7Hk2Lm9Qp", {
  coaching: {
    talk_ratio_max: 0.6,
  },
});
console.log(copilotProfile);

Updates the fields you send. Nested objects merge with the stored values; lists (stages, objections, alerts…) replace them. Calls that start afterwards use the new version.

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
<= 200 characters /^cop_[0-9A-Za-z]+$/

A copilot profile ID (cop_…).

Header Parameters

Section titled “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

Request Body

Section titled “Request Body”
Media typeapplication/json

The fields to change. Nested objects (kb, compliance, coaching, script, model) merge with the stored values; lists replace them.

object
alerts
Array<object>
<= 100 items
object
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
kind
required
string
Allowed values: keyword sentiment silence monologue talk_ratio long_call escalation
label
required
string
<= 500 characters
message
string
<= 1000 characters
notify_supervisor

Also raise it on the supervisor board.

boolean
phrases

Keyword / escalation: customer phrases.

Array<string>
<= 200 items
severity
string
Allowed values: info warn critical
threshold

Sentiment: below this (−1…1); silence / monologue: seconds; talk_ratio: agent share; long_call: minutes.

number
coaching
object
monologue_seconds_max

Continuous agent speech before “ask a question”.

number
>= 5
silence_seconds_max

Dead air before a nudge.

number
>= 2
talk_ratio_max

Agent share of talk time above which to nudge (0–1).

number
<= 1
wpm_max
number
>= 60
wpm_min
number
company

Who the agent represents.

string
<= 500 characters
compliance
object
forbidden_phrases
Array<object>
<= 300 items
object
instead

Safer wording shown on the alert.

string
<= 1000 characters
phrase
required
string
<= 500 characters
reason
string
<= 1000 characters
severity
string
Allowed values: info warn critical
required_disclosures
Array<object>
<= 50 items
object
before_stage_key

…or before leaving this stage.

string
<= 64 characters
deadline_seconds

Alert when not said this long into the call (0: before the call ends).

number
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
phrases
Array<string>
<= 200 items
script

The exact wording to read out if it was missed.

string
<= 4000 characters
fields

Details the copilot picks out of the conversation.

Array<object>
<= 100 items
object
hint

A hint for the extractor.

string
<= 500 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
options
Array<string>
<= 200 items
pattern
string
<= 400 characters
required
boolean
type
string
Allowed values: text number money phone email date enum boolean id
goal

What the call should achieve.

string
<= 4000 characters
kb
object
document_ids

Knowledge-base documents the profile may use (empty: all).

Array<string>
<= 500 items
links

Reference links shown to the agent.

Array<object>
<= 50 items
object
label
required
string
<= 200 characters
url
required
string
<= 2000 characters
min_score

Minimum confidence (0–1) to show a knowledge card unasked.

number
<= 1
language

The calls’ language (he, en, …).

string
<= 10 characters
model
object
api
string
Allowed values: chat responses
deep_path

False: the fast path only (no model calls).

boolean
fallback_model
string
<= 80 characters
max_calls_per_minute

Model calls per minute per call.

integer
<= 60
model
string
<= 80 characters
objection_similarity

Meaning-based objection match threshold (cosine).

number
<= 1
priority

Priority processing: steadier, lower latency, higher token price.

boolean
speculative

Start on stable interim text, before the utterance is final.

boolean
temperature
number
<= 2
name
string
>= 1 characters <= 120 characters
objections

The objection library.

Array<object>
<= 300 items
object
examples

Paraphrases for the meaning-based match.

Array<string>
<= 200 items
follow_up
string
<= 1000 characters
kb_query

A knowledge-base query whose facts are attached to the card.

string
<= 500 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
response
required

The recommended answer shown on the card.

string
<= 4000 characters
triggers

Customer phrases that fire it at once.

Array<string>
<= 200 items
product
string
<= 2000 characters
qa_rubric

The QA rubric this profile’s calls are scored against (empty: the organisation’s rubric).

Array<object>
<= 50 items
object
description
string
<= 2000 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
weight

Relative importance on one 0–100 scale (points out of 100); only the ratios count.

number
<= 100
script
object
flow_id
Any of:

A flow ID (flow_…).

string
<= 200 characters /^flow_[0-9A-Za-z]+$/
version
Any of:
string
Allowed value: published
stages

The call’s stages, each with a checklist (used when no script flow is set).

Array<object>
<= 50 items
object
checklist
Array<object>
<= 100 items
object
ask

The question the copilot suggests while it is open.

string
<= 1000 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
phrases

Agent phrases that tick it automatically; a trailing * matches a prefix.

Array<string>
<= 200 items
required
boolean
goal
string
<= 2000 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
tone

How the agent should sound.

string
<= 2000 characters
Example
{
  "coaching": {
    "talk_ratio_max": 0.6
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

How the real-time agent copilot coaches one kind of call: stages, objections, knowledge, fields, compliance, alerts and the QA rubric.

object
alerts
required
Array<object>
<= 100 items
object
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
kind
required
string
Allowed values: keyword sentiment silence monologue talk_ratio long_call escalation
label
required
string
<= 500 characters
message
required
string
<= 1000 characters
notify_supervisor
required

Also raise it on the supervisor board.

boolean
phrases
required

Keyword / escalation: customer phrases.

Array<string>
<= 200 items
severity
required
string
Allowed values: info warn critical
threshold
required

Sentiment: below this (−1…1); silence / monologue: seconds; talk_ratio: agent share; long_call: minutes.

number
coaching
required
object
monologue_seconds_max
required

Continuous agent speech before “ask a question”.

number
>= 5
silence_seconds_max
required

Dead air before a nudge.

number
>= 2
talk_ratio_max
required

Agent share of talk time above which to nudge (0–1).

number
<= 1
wpm_max
required
number
>= 60
wpm_min
required
number
company
required

Who the agent represents.

string
<= 500 characters
compliance
required
object
forbidden_phrases
required
Array<object>
<= 300 items
object
instead
required

Safer wording shown on the alert.

string
<= 1000 characters
phrase
required
string
<= 500 characters
reason
required
string
<= 1000 characters
severity
required
string
Allowed values: info warn critical
required_disclosures
required
Array<object>
<= 50 items
object
before_stage_key
required

…or before leaving this stage.

string
<= 64 characters
deadline_seconds
required

Alert when not said this long into the call (0: before the call ends).

number
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
phrases
required
Array<string>
<= 200 items
script
required

The exact wording to read out if it was missed.

string
<= 4000 characters
created
required

An ISO-8601 timestamp in UTC.

string format: date-time
fields
required

Details the copilot picks out of the conversation.

Array<object>
<= 100 items
object
hint
required

A hint for the extractor.

string
<= 500 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
options
required
Array<string>
<= 200 items
pattern
required
string
<= 400 characters
required
required
boolean
type
required
string
Allowed values: text number money phone email date enum boolean id
goal
required

What the call should achieve.

string
<= 4000 characters
id
required

The profile’s ID.

string
/^cop_[0-9A-Za-z]+$/
kb
required
object
document_ids
required

Knowledge-base documents the profile may use (empty: all).

Array<string>
<= 500 items
links
required

Reference links shown to the agent.

Array<object>
<= 50 items
object
label
required
string
<= 200 characters
url
required
string
<= 2000 characters
min_score
required

Minimum confidence (0–1) to show a knowledge card unasked.

number
<= 1
language
required

The calls’ language (he, en, …).

string
<= 10 characters
livemode
required

true in live mode, false in test mode.

boolean
model
required
object
api
required
string
Allowed values: chat responses
deep_path
required

False: the fast path only (no model calls).

boolean
fallback_model
required
string
<= 80 characters
max_calls_per_minute
required

Model calls per minute per call.

integer
<= 60
model
required
string
<= 80 characters
objection_similarity
required

Meaning-based objection match threshold (cosine).

number
<= 1
priority
required

Priority processing: steadier, lower latency, higher token price.

boolean
speculative
required

Start on stable interim text, before the utterance is final.

boolean
temperature
required
number
<= 2
name
required
string
object
required
string
Allowed value: copilot_profile
objections
required

The objection library.

Array<object>
<= 300 items
object
examples
required

Paraphrases for the meaning-based match.

Array<string>
<= 200 items
follow_up
required
string
<= 1000 characters
kb_query
required

A knowledge-base query whose facts are attached to the card.

string
<= 500 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
response
required

The recommended answer shown on the card.

string
<= 4000 characters
triggers
required

Customer phrases that fire it at once.

Array<string>
<= 200 items
product
required
string
<= 2000 characters
qa_rubric
required

The QA rubric this profile’s calls are scored against (empty: the organisation’s rubric).

Array<object>
<= 50 items
object
description
required
string
<= 2000 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
weight
required

Relative importance on one 0–100 scale (points out of 100); only the ratios count.

number
<= 100
script
required
object
flow_id
required
Any of:

A flow ID (prefix flow_).

string
/^flow_[0-9A-Za-z]+$/
version
required
Any of:
string
Allowed value: published
stages
required

The call’s stages, each with a checklist (used when no script flow is set).

Array<object>
<= 50 items
object
checklist
required
Array<object>
<= 100 items
object
ask
required

The question the copilot suggests while it is open.

string
<= 1000 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
phrases
required

Agent phrases that tick it automatically; a trailing * matches a prefix.

Array<string>
<= 200 items
required
required
boolean
goal
required
string
<= 2000 characters
key
required

Your stable identifier of the item.

string
>= 1 characters <= 64 characters
label
required
string
<= 500 characters
template_id
required

The template it was created from.

string | null
tone
required

How the agent should sound.

string
<= 2000 characters
updated
required

An ISO-8601 timestamp in UTC.

string format: date-time
version
required

Goes up on every change.

integer
>= -9007199254740991 <= 9007199254740991
Example
{
  "alerts": [
    {
      "key": "escalation",
      "kind": "escalation",
      "label": "Asks for a manager",
      "message": "Acknowledge and offer a solution.",
      "notify_supervisor": true,
      "phrases": [
        "manager"
      ],
      "severity": "critical",
      "threshold": 0
    }
  ],
  "coaching": {
    "monologue_seconds_max": 40,
    "silence_seconds_max": 7,
    "talk_ratio_max": 0.65,
    "wpm_max": 175,
    "wpm_min": 0
  },
  "company": "Acme",
  "compliance": {
    "forbidden_phrases": [
      {
        "instead": "In most cases",
        "phrase": "guaranteed",
        "reason": "No guarantees",
        "severity": "warn"
      }
    ],
    "required_disclosures": []
  },
  "created": "2026-11-03T09:14:22.000Z",
  "fields": [
    {
      "hint": "",
      "key": "budget",
      "label": "Monthly budget",
      "options": [],
      "pattern": "",
      "required": false,
      "type": "money"
    }
  ],
  "goal": "Book a demo or a clear next step.",
  "id": "cop_8Ps2Ux5Zc7Eh0Jm3Or6Tw9",
  "kb": {
    "document_ids": [
      "kbd_6Nq0Sv3Xa5Cf8Hk1Mp4Rt7"
    ],
    "links": [],
    "min_score": 0.35
  },
  "language": "en",
  "livemode": true,
  "model": {
    "api": "chat",
    "deep_path": true,
    "fallback_model": "gpt-4.1-nano",
    "max_calls_per_minute": 12,
    "model": "gpt-4.1-mini",
    "objection_similarity": 0.72,
    "priority": true,
    "speculative": true,
    "temperature": 0.3
  },
  "name": "Outbound sales",
  "object": "copilot_profile",
  "objections": [
    {
      "examples": [
        "it costs too much"
      ],
      "follow_up": "What do you pay now?",
      "kb_query": "price list",
      "key": "price",
      "label": "Too expensive",
      "response": "Compare it with what downtime costs you today.",
      "triggers": [
        "too expensive"
      ]
    }
  ],
  "product": "Acme Cloud PBX",
  "qa_rubric": [
    {
      "description": "Asked open questions first.",
      "key": "discovery",
      "label": "Discovery",
      "weight": 60
    },
    {
      "description": "Agreed a dated next step.",
      "key": "close",
      "label": "Next step",
      "weight": 40
    }
  ],
  "script": {
    "flow_id": null,
    "version": "published"
  },
  "stages": [
    {
      "checklist": [
        {
          "ask": "",
          "key": "recorded",
          "label": "Say the call is recorded",
          "phrases": [
            "this call is recorded"
          ],
          "required": true
        }
      ],
      "goal": "Introduce yourself and ask for two minutes",
      "key": "opening",
      "label": "Opening"
    }
  ],
  "template_id": "sales-outbound",
  "tone": "Warm, confident, never pushy.",
  "updated": "2026-11-03T09:14:22.000Z",
  "version": 4
}

400

Section titled “400”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

401

Section titled “401”

No valid API key was sent.

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

403

Section titled “403”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

404

Section titled “404”

No object with this ID exists in this organisation and mode.

Media typeapplication/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": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

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

429

Section titled “429”

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

Media typeapplication/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

Section titled “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

Section titled “500”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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