> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cozmox.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete Phone Number
## OpenAPI
````yaml delete /phone-number/{id}
openapi: 3.0.0
info:
title: cozmox API
description: Voice AI for developers.
version: '1'
contact: {}
servers:
- description: Cozmox APIs
url: https://api.cozmox.ai
- url: https://api.cozmox.ai
security: []
tags: []
paths:
/phone-number/{id}:
delete:
tags:
- Phone Numbers
summary: Delete Phone Number
operationId: PhoneNumberController_remove
parameters:
- name: id
required: true
in: path
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: PhoneNumber
oneOf:
- $ref: '#/components/schemas/ByoPhoneNumber'
title: ByoPhoneNumber
- $ref: '#/components/schemas/TwilioPhoneNumber'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/VonagePhoneNumber'
title: VonagePhoneNumber
- $ref: '#/components/schemas/cozmoxPhoneNumber'
title: cozmoxPhoneNumber
- $ref: '#/components/schemas/TelnyxPhoneNumber'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/ByoPhoneNumber'
twilio: '#/components/schemas/TwilioPhoneNumber'
vonage: '#/components/schemas/VonagePhoneNumber'
cozmox: '#/components/schemas/cozmoxPhoneNumber'
telnyx: '#/components/schemas/TelnyxPhoneNumber'
security:
- bearer: []
components:
schemas:
ByoPhoneNumber:
type: object
properties:
fallbackDestination:
description: >-
This is the fallback destination an inbound call will be transferred
to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is
hung up with an error message.
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: >-
This is the hooks that will be used for incoming calls to this phone
number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
provider:
type: string
description: >-
This is to bring your own phone numbers from your own SIP trunks or
Carriers.
enum:
- byo-phone-number
numberE164CheckEnabled:
type: boolean
description: >-
This is the flag to toggle the E164 check for the `number` field.
This is an advanced property which should be used if you know your
use case requires it.
Use cases:
- `false`: To allow non-E164 numbers like `+001234567890`, `1234`,
or `abc`. This is useful for dialing out to non-E164 numbers on your
SIP trunks.
- `true` (default): To allow only E164 numbers like `+14155551234`.
This is standard for PSTN calls.
If `false`, the `number` is still required to only contain
alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`).
@default true (E164 check is enabled)
default: true
id:
type: string
description: This is the unique identifier for the phone number.
orgId:
type: string
description: >-
This is the unique identifier for the org that this phone number
belongs to.
createdAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
created.
updatedAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
last updated.
status:
type: string
description: This is the status of the phone number.
enum:
- active
- activating
- blocked
name:
type: string
description: >-
This is the name of the phone number. This is just for your own
reference.
maxLength: 40
assistantId:
type: string
description: >-
This is the assistant that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
workflowId:
type: string
description: >-
This is the workflow that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
squadId:
type: string
description: >-
This is the squad that will be used for incoming calls to this phone
number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
server:
description: >-
This is where cozmox will send webhooks. You can find all webhooks
available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server
allOf:
- $ref: '#/components/schemas/Server'
number:
type: string
description: This is the number of the customer.
minLength: 3
maxLength: 40
credentialId:
type: string
description: >-
This is the credential of your own SIP trunk or Carrier (type
`byo-sip-trunk`) which can be used to make calls to this phone
number.
You can add the SIP trunk or Carrier credential in the Provider
Credentials page on the Dashboard to get the credentialId.
required:
- provider
- id
- orgId
- createdAt
- updatedAt
- credentialId
TwilioPhoneNumber:
type: object
properties:
fallbackDestination:
description: >-
This is the fallback destination an inbound call will be transferred
to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is
hung up with an error message.
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: >-
This is the hooks that will be used for incoming calls to this phone
number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
provider:
type: string
description: This is to use numbers bought on Twilio.
enum:
- twilio
smsEnabled:
type: boolean
description: >-
Controls whether cozmox sets the messaging webhook URL on the Twilio
number during import.
If set to `false`, cozmox will not update the Twilio messaging URL,
leaving it as is.
If `true` or omitted (default), cozmox will configure both the voice
and messaging URLs.
@default true
default: true
id:
type: string
description: This is the unique identifier for the phone number.
orgId:
type: string
description: >-
This is the unique identifier for the org that this phone number
belongs to.
createdAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
created.
updatedAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
last updated.
status:
type: string
description: This is the status of the phone number.
enum:
- active
- activating
- blocked
twilioAuthToken:
type: string
description: This is the Twilio Auth Token for the phone number.
twilioApiKey:
type: string
description: This is the Twilio API Key for the phone number.
twilioApiSecret:
type: string
description: This is the Twilio API Secret for the phone number.
name:
type: string
description: >-
This is the name of the phone number. This is just for your own
reference.
maxLength: 40
assistantId:
type: string
description: >-
This is the assistant that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
workflowId:
type: string
description: >-
This is the workflow that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
squadId:
type: string
description: >-
This is the squad that will be used for incoming calls to this phone
number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
server:
description: >-
This is where cozmox will send webhooks. You can find all webhooks
available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server
allOf:
- $ref: '#/components/schemas/Server'
number:
type: string
description: These are the digits of the phone number you own on your Twilio.
twilioAccountSid:
type: string
description: This is the Twilio Account SID for the phone number.
required:
- provider
- id
- orgId
- createdAt
- updatedAt
- number
- twilioAccountSid
VonagePhoneNumber:
type: object
properties:
fallbackDestination:
description: >-
This is the fallback destination an inbound call will be transferred
to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is
hung up with an error message.
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: >-
This is the hooks that will be used for incoming calls to this phone
number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
provider:
type: string
description: This is to use numbers bought on Vonage.
enum:
- vonage
id:
type: string
description: This is the unique identifier for the phone number.
orgId:
type: string
description: >-
This is the unique identifier for the org that this phone number
belongs to.
createdAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
created.
updatedAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
last updated.
status:
type: string
description: This is the status of the phone number.
enum:
- active
- activating
- blocked
name:
type: string
description: >-
This is the name of the phone number. This is just for your own
reference.
maxLength: 40
assistantId:
type: string
description: >-
This is the assistant that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
workflowId:
type: string
description: >-
This is the workflow that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
squadId:
type: string
description: >-
This is the squad that will be used for incoming calls to this phone
number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
server:
description: >-
This is where cozmox will send webhooks. You can find all webhooks
available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server
allOf:
- $ref: '#/components/schemas/Server'
number:
type: string
description: These are the digits of the phone number you own on your Vonage.
credentialId:
type: string
description: >-
This is the credential you added in dashboard.cozmox.ai/keys. This
is used to configure the number to send inbound calls to cozmox,
make outbound calls and do live call updates like transfers and
hangups.
required:
- provider
- id
- orgId
- createdAt
- updatedAt
- number
- credentialId
cozmoxPhoneNumber:
type: object
properties:
fallbackDestination:
description: >-
This is the fallback destination an inbound call will be transferred
to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is
hung up with an error message.
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: >-
This is the hooks that will be used for incoming calls to this phone
number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
provider:
type: string
description: This is to create free SIP phone numbers on cozmox.
enum:
- cozmox
id:
type: string
description: This is the unique identifier for the phone number.
orgId:
type: string
description: >-
This is the unique identifier for the org that this phone number
belongs to.
createdAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
created.
updatedAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
last updated.
status:
type: string
description: This is the status of the phone number.
enum:
- active
- activating
- blocked
number:
type: string
description: These are the digits of the phone number you purchased from cozmox.
name:
type: string
description: >-
This is the name of the phone number. This is just for your own
reference.
maxLength: 40
assistantId:
type: string
description: >-
This is the assistant that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
workflowId:
type: string
description: >-
This is the workflow that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
squadId:
type: string
description: >-
This is the squad that will be used for incoming calls to this phone
number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
server:
description: >-
This is where cozmox will send webhooks. You can find all webhooks
available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server
allOf:
- $ref: '#/components/schemas/Server'
numberDesiredAreaCode:
type: string
description: This is the area code of the phone number to purchase.
minLength: 3
maxLength: 3
sipUri:
type: string
description: >-
This is the SIP URI of the phone number. You can SIP INVITE this.
The assistant attached to this number will answer.
This is case-insensitive.
authentication:
description: >-
This enables authentication for incoming SIP INVITE requests to the
`sipUri`.
If not set, any username/password to the 401 challenge of the SIP
INVITE will be accepted.
allOf:
- $ref: '#/components/schemas/SipAuthentication'
required:
- provider
- id
- orgId
- createdAt
- updatedAt
TelnyxPhoneNumber:
type: object
properties:
fallbackDestination:
description: >-
This is the fallback destination an inbound call will be transferred
to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is
hung up with an error message.
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: >-
This is the hooks that will be used for incoming calls to this phone
number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
provider:
type: string
description: This is to use numbers bought on Telnyx.
enum:
- telnyx
id:
type: string
description: This is the unique identifier for the phone number.
orgId:
type: string
description: >-
This is the unique identifier for the org that this phone number
belongs to.
createdAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
created.
updatedAt:
format: date-time
type: string
description: >-
This is the ISO 8601 date-time string of when the phone number was
last updated.
status:
type: string
description: This is the status of the phone number.
enum:
- active
- activating
- blocked
name:
type: string
description: >-
This is the name of the phone number. This is just for your own
reference.
maxLength: 40
assistantId:
type: string
description: >-
This is the assistant that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
workflowId:
type: string
description: >-
This is the workflow that will be used for incoming calls to this
phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
squadId:
type: string
description: >-
This is the squad that will be used for incoming calls to this phone
number.
If neither `assistantId`, `squadId`, nor `workflowId` is set,
`assistant-request` will be sent to your Server URL. Check
`ServerMessage` and `ServerMessageResponse` for the shape of the
message and response that is expected.
server:
description: >-
This is where cozmox will send webhooks. You can find all webhooks
available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server
allOf:
- $ref: '#/components/schemas/Server'
number:
type: string
description: These are the digits of the phone number you own on your Telnyx.
credentialId:
type: string
description: >-
This is the credential you added in dashboard.cozmox.ai/keys. This
is used to configure the number to send inbound calls to cozmox,
make outbound calls and do live call updates like transfers and
hangups.
required:
- provider
- id
- orgId
- createdAt
- updatedAt
- number
- credentialId
TransferDestinationNumber:
type: object
properties:
message:
description: >-
This is spoken to the customer before connecting them to the
destination.
Usage:
- If this is not provided and transfer tool messages is not
provided, default is "Transferring the call now".
- If set to "", nothing is spoken. This is useful when you want to
silently transfer. This is especially useful when transferring
between assistants in a squad. In this scenario, you likely also
want to set
`assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message`
for the destination assistant.
This accepts a string or a ToolMessageStart class. Latter is useful
if you want to specify multiple messages for different languages
through the `contents` field.
oneOf:
- type: string
- $ref: '#/components/schemas/CustomMessage'
type:
type: string
enum:
- number
numberE164CheckEnabled:
type: boolean
description: >-
This is the flag to toggle the E164 check for the `number` field.
This is an advanced property which should be used if you know your
use case requires it.
Use cases:
- `false`: To allow non-E164 numbers like `+001234567890`, `1234`,
or `abc`. This is useful for dialing out to non-E164 numbers on your
SIP trunks.
- `true` (default): To allow only E164 numbers like `+14155551234`.
This is standard for PSTN calls.
If `false`, the `number` is still required to only contain
alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`).
@default true (E164 check is enabled)
default: true
number:
type: string
description: This is the phone number to transfer the call to.
minLength: 3
maxLength: 40
extension:
type: string
description: >-
This is the extension to dial after transferring the call to the
`number`.
minLength: 1
maxLength: 10
callerId:
type: string
description: >-
This is the caller ID to use when transferring the call to the
`number`.
Usage:
- If not provided, the caller ID will be the number the call is
coming from. Example, +14151111111 calls in to and the assistant
transfers out to +16470000000. +16470000000 will see +14151111111 as
the caller.
- To change this behavior, provide a `callerId`.
- Set to '{{customer.number}}' to always use the customer's number
as the caller ID.
- Set to '{{phoneNumber.number}}' to always use the phone number of
the assistant as the caller ID.
- Set to any E164 number to always use that number as the caller ID.
This needs to be a number that is owned or verified by your
Transport provider like Twilio.
For Twilio, you can read up more here:
https://www.twilio.com/docs/voice/twiml/dial#callerid
maxLength: 40
transferPlan:
description: >-
This configures how transfer is executed and the experience of the
destination party receiving the call. Defaults to `blind-transfer`.
@default `transferPlan.mode='blind-transfer'`
allOf:
- $ref: '#/components/schemas/TransferPlan'
description:
type: string
description: >-
This is the description of the destination, used by the AI to choose
when and how to transfer the call.
required:
- type
- number
TransferDestinationSip:
type: object
properties:
message:
description: >-
This is spoken to the customer before connecting them to the
destination.
Usage:
- If this is not provided and transfer tool messages is not
provided, default is "Transferring the call now".
- If set to "", nothing is spoken. This is useful when you want to
silently transfer. This is especially useful when transferring
between assistants in a squad. In this scenario, you likely also
want to set
`assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message`
for the destination assistant.
This accepts a string or a ToolMessageStart class. Latter is useful
if you want to specify multiple messages for different languages
through the `contents` field.
oneOf:
- type: string
- $ref: '#/components/schemas/CustomMessage'
type:
type: string
enum:
- sip
sipUri:
type: string
description: This is the SIP URI to transfer the call to.
transferPlan:
description: >-
This configures how transfer is executed and the experience of the
destination party receiving the call. Defaults to `blind-transfer`.
@default `transferPlan.mode='blind-transfer'`
allOf:
- $ref: '#/components/schemas/TransferPlan'
sipHeaders:
type: object
description: >-
These are custom headers to be added to SIP refer during transfer
call.
description:
type: string
description: >-
This is the description of the destination, used by the AI to choose
when and how to transfer the call.
required:
- type
- sipUri
PhoneNumberHookCallRinging:
type: object
properties:
'on':
type: string
description: This is the event to trigger the hook on
enum:
- call.ringing
maxLength: 1000
do:
type: array
description: This is the set of actions to perform when the hook triggers
items:
oneOf:
- $ref: '#/components/schemas/TransferPhoneNumberHookAction'
title: TransferPhoneNumberHookAction
- $ref: '#/components/schemas/SayPhoneNumberHookAction'
title: SayPhoneNumberHookAction
required:
- 'on'
- do
Server:
type: object
properties:
timeoutSeconds:
type: number
description: >-
This is the timeout in seconds for the request. Defaults to 20
seconds.
@default 20
minimum: 1
maximum: 300
example: 20
url:
type: string
description: This is where the request will be sent.
headers:
type: object
description: |-
These are the headers to include in the request.
Each key-value pair represents a header name and its value.
backoffPlan:
description: >-
This is the backoff plan if the request fails. Defaults to undefined
(the request will not be retried).
@default undefined (the request will not be retried)
allOf:
- $ref: '#/components/schemas/BackoffPlan'
SipAuthentication:
type: object
properties:
realm:
type: string
description: >-
This will be expected in the `realm` field of the `authorization`
header of the SIP INVITE. Defaults to sip.cozmox.ai.
username:
type: string
description: >-
This will be expected in the `username` field of the `authorization`
header of the SIP INVITE.
minLength: 20
maxLength: 40
password:
type: string
description: >-
This will be expected to generate the `response` field of the
`authorization` header of the SIP INVITE, through digest
authentication.
minLength: 20
maxLength: 40
required:
- username
- password
CustomMessage:
type: object
properties:
contents:
type: array
description: >-
This is an alternative to the `content` property. It allows to
specify variants of the same content, one per language.
Usage:
- If your assistants are multilingual, you can provide content for
each language.
- If you don't provide content for a language, the first item in the
array will be automatically translated to the active language at
that moment.
This will override the `content` property.
items:
oneOf:
- $ref: '#/components/schemas/TextContent'
title: Text
type:
type: string
description: This is a custom message.
enum:
- custom-message
content:
type: string
description: >-
This is the content that the assistant will say when this message is
triggered.
maxLength: 1000
required:
- type
TransferPlan:
type: object
properties:
mode:
type: string
description: >-
This configures how transfer is executed and the experience of the
destination party receiving the call.
Usage:
- `blind-transfer`: The assistant forwards the call to the
destination without any message or summary.
- `blind-transfer-add-summary-to-sip-header`: The assistant forwards
the call to the destination and adds a SIP header X-Transfer-Summary
to the call to include the summary.
- `warm-transfer-say-message`: The assistant dials the destination,
delivers the `message` to the destination party, connects the
customer, and leaves the call.
- `warm-transfer-say-summary`: The assistant dials the destination,
provides a summary of the call to the destination party, connects
the customer, and leaves the call.
-
`warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`:
The assistant dials the destination, waits for the operator to
speak, delivers the `message` to the destination party, and then
connects the customer.
-
`warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`:
The assistant dials the destination, waits for the operator to
speak, provides a summary of the call to the destination party, and
then connects the customer.
- `warm-transfer-twiml`: The assistant dials the destination,
executes the twiml instructions on the destination call leg,
connects the customer, and leaves the call.
- `warm-transfer-experimental`: The assistant puts the customer on
hold, dials the destination, and if the destination answers (and is
human), delivers a message or summary before connecting the
customer. If the destination is unreachable or not human (e.g., with
voicemail detection), the assistant delivers the `fallbackMessage`
to the customer and optionally ends the call.
@default 'blind-transfer'
enum:
- blind-transfer
- blind-transfer-add-summary-to-sip-header
- warm-transfer-say-message
- warm-transfer-say-summary
- warm-transfer-twiml
- >-
warm-transfer-wait-for-operator-to-speak-first-and-then-say-message
- >-
warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary
- warm-transfer-experimental
message:
description: >-
This is the message the assistant will deliver to the destination
party before connecting the customer.
Usage:
- Used only when `mode` is
`blind-transfer-add-summary-to-sip-header`,
`warm-transfer-say-message`,
`warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`,
or `warm-transfer-experimental`.
oneOf:
- type: string
- $ref: '#/components/schemas/CustomMessage'
timeout:
type: number
description: >-
This is the timeout in seconds for the
warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary
@default 60
minimum: 1
maximum: 600
default: 60
sipVerb:
type: object
description: |-
This specifies the SIP verb to use while transferring the call.
- 'refer': Uses SIP REFER to transfer the call (default)
- 'bye': Ends current call with SIP BYE
- 'dial': Uses SIP DIAL to transfer the call
default: refer
enum:
- refer
- bye
- dial
holdAudioUrl:
type: string
description: >-
This is the URL to an audio file played while the customer is on
hold during transfer.
Usage:
- Used only when `mode` is `warm-transfer-experimental`.
- Used when transferring calls to play hold audio for the customer.
- Must be a publicly accessible URL to an audio file.
- Supported formats: MP3 and WAV.
- If not provided, the default hold audio will be used.
transferCompleteAudioUrl:
type: string
description: >-
This is the URL to an audio file played after the warm transfer
message or summary is delivered to the destination party.
It can be used to play a custom sound like 'beep' to notify that the
transfer is complete.
Usage:
- Used only when `mode` is `warm-transfer-experimental`.
- Used when transferring calls to play hold audio for the
destination party.
- Must be a publicly accessible URL to an audio file.
- Supported formats: MP3 and WAV.
twiml:
type: string
description: >-
This is the TwiML instructions to execute on the destination call
leg before connecting the customer.
Usage:
- Used only when `mode` is `warm-transfer-twiml`.
- Supports only `Play`, `Say`, `Gather`, `Hangup` and `Pause` verbs.
- Maximum length is 4096 characters.
Example:
```
Hello, transferring a customer
to you.
They called about billing questions.
```
maxLength: 4096
summaryPlan:
description: >-
This is the plan for generating a summary of the call to present to
the destination party.
Usage:
- Used only when `mode` is
`blind-transfer-add-summary-to-sip-header` or
`warm-transfer-say-summary` or
`warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`
or `warm-transfer-experimental`.
allOf:
- $ref: '#/components/schemas/SummaryPlan'
sipHeadersInReferToEnabled:
type: boolean
description: >-
This flag includes the sipHeaders from above in the refer to sip uri
as url encoded query params.
@default false
fallbackPlan:
description: >-
This configures the fallback plan when the transfer fails
(destination unreachable, busy, or not human).
Usage:
- Used only when `mode` is `warm-transfer-experimental`.
- If not provided when using `warm-transfer-experimental`, a default
message will be used.
allOf:
- $ref: '#/components/schemas/TransferFallbackPlan'
required:
- mode
TransferPhoneNumberHookAction:
type: object
properties:
type:
type: string
description: This is the type of action - must be "transfer"
enum:
- transfer
destination:
description: >-
This is the destination details for the transfer - can be a phone
number or SIP URI
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
required:
- type
SayPhoneNumberHookAction:
type: object
properties:
type:
type: string
description: This is the type of action - must be "say"
enum:
- say
exact:
type: string
description: This is the message to say
maxLength: 4000
required:
- type
- exact
BackoffPlan:
type: object
properties:
type:
type: object
description: |-
This is the type of backoff plan to use. Defaults to fixed.
@default fixed
enum:
- fixed
- exponential
example: fixed
maxRetries:
type: number
description: >-
This is the maximum number of retries to attempt if the request
fails. Defaults to 0 (no retries).
@default 0
minimum: 0
maximum: 10
example: 0
baseDelaySeconds:
type: number
description: >-
This is the base delay in seconds. For linear backoff, this is the
delay between each retry. For exponential backoff, this is the
initial delay.
minimum: 0
maximum: 10
example: 1
required:
- type
- maxRetries
- baseDelaySeconds
TextContent:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
language:
type: string
enum:
- aa
- ab
- ae
- af
- ak
- am
- an
- ar
- as
- av
- ay
- az
- ba
- be
- bg
- bh
- bi
- bm
- bn
- bo
- br
- bs
- ca
- ce
- ch
- co
- cr
- cs
- cu
- cv
- cy
- da
- de
- dv
- dz
- ee
- el
- en
- eo
- es
- et
- eu
- fa
- ff
- fi
- fj
- fo
- fr
- fy
- ga
- gd
- gl
- gn
- gu
- gv
- ha
- he
- hi
- ho
- hr
- ht
- hu
- hy
- hz
- ia
- id
- ie
- ig
- ii
- ik
- io
- is
- it
- iu
- ja
- jv
- ka
- kg
- ki
- kj
- kk
- kl
- km
- kn
- ko
- kr
- ks
- ku
- kv
- kw
- ky
- la
- lb
- lg
- li
- ln
- lo
- lt
- lu
- lv
- mg
- mh
- mi
- mk
- ml
- mn
- mr
- ms
- mt
- my
- na
- nb
- nd
- ne
- ng
- nl
- nn
- 'no'
- nr
- nv
- ny
- oc
- oj
- om
- or
- os
- pa
- pi
- pl
- ps
- pt
- qu
- rm
- rn
- ro
- ru
- rw
- sa
- sc
- sd
- se
- sg
- si
- sk
- sl
- sm
- sn
- so
- sq
- sr
- ss
- st
- su
- sv
- sw
- ta
- te
- tg
- th
- ti
- tk
- tl
- tn
- to
- tr
- ts
- tt
- tw
- ty
- ug
- uk
- ur
- uz
- ve
- vi
- vo
- wa
- wo
- xh
- yi
- yue
- yo
- za
- zh
- zu
required:
- type
- text
- language
SummaryPlan:
type: object
properties:
messages:
description: >-
These are the messages used to generate the summary.
@default: ```
[
{
"role": "system",
"content": "You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences. DO NOT return anything except the summary."
},
{
"role": "user",
"content": "Here is the transcript:\n\n{{transcript}}\n\n. Here is the ended reason of the call:\n\n{{endedReason}}\n\n"
}
]```
You can customize by providing any messages you want.
Here are the template variables available:
- {{transcript}}: The transcript of the call from
`call.artifact.transcript`
- {{systemPrompt}}: The system prompt of the call from
`assistant.model.messages[type=system].content`
- {{endedReason}}: The ended reason of the call from
`call.endedReason`
type: array
items:
type: object
enabled:
type: boolean
description: >-
This determines whether a summary is generated and stored in
`call.analysis.summary`. Defaults to true.
Usage:
- If you want to disable the summary, set this to false.
@default true
timeoutSeconds:
type: number
description: >-
This is how long the request is tried before giving up. When request
times out, `call.analysis.summary` will be empty.
Usage:
- To guarantee the summary is generated, set this value high. Note,
this will delay the end of call report in cases where model is slow
to respond.
@default 5 seconds
minimum: 1
maximum: 60
TransferFallbackPlan:
type: object
properties:
message:
description: >-
This is the message the assistant will deliver to the customer if
the transfer fails.
oneOf:
- type: string
- $ref: '#/components/schemas/CustomMessage'
endCallEnabled:
type: boolean
description: >-
This controls what happens after delivering the failure message to
the customer.
- true: End the call after delivering the failure message (default)
- false: Keep the assistant on the call to continue handling the
customer's request
@default true
default: true
required:
- message
securitySchemes:
bearer:
scheme: bearer
bearerFormat: Bearer
type: http
description: Retrieve your API Key from [Dashboard](dashboard.cozmox.ai).
````