Schemas

VoiceOtpRequest

from

string · required

Caller ID phone number in E.164 format. Must be a DID owned by the authenticated account.

Example: +14155550100

to

string · required

Destination phone number in E.164 format

Example: +14155551234

otp

string · pattern: ^[0-9]{1,10}$ · required

One-time password to deliver (digits only, max 10 characters)

Example: 123456

session_id

string · uuid

Optional session identifier. If not provided, one will be generated.

repeat

integer · min: 1 · max: 3

Number of times to repeat the OTP

Default: 2

language

string

BCP-47 language code for speech synthesis

Example: en-US

Default: en-US

speaking_rate

number · float · min: 0.25 · max: 2

Speech rate multiplier

Default: 1

custom_message

string · maxLength: 40

Custom message template (max 40 characters). Use {otp} as placeholder.

Example: Your code is {otp}

callback_url

string · uri

Webhook URL for call status notifications

VoiceOtpResponse

session_id

string · uuid

Unique identifier for the call session

status

string

Current call status

Example: queued

TtsRequest

from

string · required

Caller ID phone number in E.164 format. Must be a DID owned by the authenticated account.

Example: +14155550100

to

string[] · minItems: 1 · maxItems: 25 · required

Destination phone numbers in E.164 format (1-25 numbers)

session_id

string · uuid

Optional session identifier. If not provided, one will be generated. For multiple recipients, all calls share this session ID.

message

string

Text to synthesize. Mutually exclusive with resource_id.

resource_id

string · uuid

Pre-uploaded audio resource. Mutually exclusive with message.

language

string

BCP-47 language code for speech synthesis

Default: en-US

speaking_rate

number · float · min: 0.25 · max: 2

Speech rate multiplier

Default: 1

callback_url

string · uri

Webhook URL for call status notifications

TtsResponse

session_id

string · uuid

Unique identifier for the session. For multiple recipients, this serves as the batch ID.

status

string

Current status

Example: queued

SessionResponse

id

string · uuid

Unique identifier for this call record

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

session_id

string | null · uuid

Batch session ID (for TTS with multiple recipients)

Example: b2c3d4e5-f6a7-8901-bcde-f12345678901

session_type

string · enum

Type of session

Enum values:

otp

tts

Example: otp

from

string

Caller ID (DID phone number)

Example: +14155550100

to

string

Recipient phone number

Example: +14155551234

status

string · enum

Session status

Enum values:

queued

pending

delivered

failed

Example: delivered

call_status

string | null

Underlying call status from the telephony provider

Example: completed

cost

number | null · decimal

Cost of the call in account currency

Example: 0.05

queued_at

string | null · date-time

Timestamp when the session was queued

Example: 2024-01-15T10:30:00Z

initiated_at

string | null · date-time

Timestamp when the call was initiated

Example: 2024-01-15T10:30:01Z

answered_at

string | null · date-time

Timestamp when the call was answered

Example: 2024-01-15T10:30:05Z

completed_at

string | null · date-time

Timestamp when the call completed

Example: 2024-01-15T10:30:25Z

SessionListResponse

SessionResponse[]

uri

string

Current request URI

Example: /v1/chatterwave/sessions/

page

integer

Current page number

Example: 0

page_size

integer

Results per page

Example: 50

first_page_uri

string

URI for the first page

Example: /v1/chatterwave/sessions/?page=0&page_size=50

next_page_uri

string | null

URI for the next page

Example: /v1/chatterwave/sessions/?page=1&page_size=50

previous_page_uri

string | null

URI for the previous page

Example: null

ResourceResponse

resource_id

string · uuid

Unique identifier for the resource

file_name

string

Original or provided file name

file_type

string

MIME type of the uploaded file

Example: audio/wav

file_size_bytes

integer · int64

File size in bytes

created_at

string · date-time

Timestamp of resource creation

ResourceListResponse

ResourceResponse[]

uri

string

Current request URI

Example: /v1/chatterwave/resources/

page

integer

Current page number

Example: 0

page_size

integer

Results per page

Example: 50

first_page_uri

string

URI for the first page

Example: /v1/chatterwave/resources/?page=0&page_size=50

next_page_uri

string | null

URI for the next page

Example: /v1/chatterwave/resources/?page=1&page_size=50

previous_page_uri

string | null

URI for the previous page

Example: null

Error

error

string · required

Error code. Possible values:

not_found - Resource not found
invalid_input - Invalid input data
validation_error - Validation failed
insufficient_balance - Account balance too low
free_trial_exceeded - Free trial limit reached
invalid_recipient_count - Must have 1-25 recipients
mutually_exclusive_fields - Cannot provide both message and resource_id
business_rule_violation - Business rule check failed
external_service_error - Upstream service unavailable

Example: not_found

message

string · required

Human-readable error description

Example: DID not found

VoiceOtpRequest

from

string · required

Caller ID phone number in E.164 format. Must be a DID owned by the authenticated account.

Example: +14155550100

to

string · required

Destination phone number in E.164 format

Example: +14155551234

otp

string · pattern: ^[0-9]{1,10}$ · required

One-time password to deliver (digits only, max 10 characters)

Example: 123456

session_id

string · uuid

Optional session identifier. If not provided, one will be generated.

repeat

integer · min: 1 · max: 3

Number of times to repeat the OTP

Default: 2

language

string

BCP-47 language code for speech synthesis

Example: en-US

Default: en-US

speaking_rate

number · float · min: 0.25 · max: 2

Speech rate multiplier

Default: 1

custom_message

string · maxLength: 40

Custom message template (max 40 characters). Use {otp} as placeholder.

Example: Your code is {otp}

callback_url

string · uri

Webhook URL for call status notifications

TtsRequest

from

string · required

Caller ID phone number in E.164 format. Must be a DID owned by the authenticated account.

Example: +14155550100

to

string[] · minItems: 1 · maxItems: 25 · required

Destination phone numbers in E.164 format (1-25 numbers)

session_id

string · uuid

Optional session identifier. If not provided, one will be generated. For multiple recipients, all calls share this session ID.

message

string

Text to synthesize. Mutually exclusive with resource_id.

resource_id

string · uuid

Pre-uploaded audio resource. Mutually exclusive with message.

language

string

BCP-47 language code for speech synthesis

Default: en-US

speaking_rate

number · float · min: 0.25 · max: 2

Speech rate multiplier

Default: 1

callback_url

string · uri

Webhook URL for call status notifications

SessionResponse

id

string · uuid

Unique identifier for this call record

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

session_id

string | null · uuid

Batch session ID (for TTS with multiple recipients)

Example: b2c3d4e5-f6a7-8901-bcde-f12345678901

session_type

string · enum

Type of session

Enum values:

otp

tts

Example: otp

from

string

Caller ID (DID phone number)

Example: +14155550100

to

string

Recipient phone number

Example: +14155551234

status

string · enum

Session status

Enum values:

queued

pending

delivered

failed

Example: delivered

call_status

string | null

Underlying call status from the telephony provider

Example: completed

cost

number | null · decimal

Cost of the call in account currency

Example: 0.05

queued_at

string | null · date-time

Timestamp when the session was queued

Example: 2024-01-15T10:30:00Z

initiated_at

string | null · date-time

Timestamp when the call was initiated

Example: 2024-01-15T10:30:01Z

answered_at

string | null · date-time

Timestamp when the call was answered

Example: 2024-01-15T10:30:05Z

completed_at

string | null · date-time

Timestamp when the call completed

Example: 2024-01-15T10:30:25Z

SessionListResponse

SessionResponse[]

uri

string

Current request URI

Example: /v1/chatterwave/sessions/

page

integer

Current page number

Example: 0

page_size

integer

Results per page

Example: 50

first_page_uri

string

URI for the first page

Example: /v1/chatterwave/sessions/?page=0&page_size=50

next_page_uri

string | null

URI for the next page

Example: /v1/chatterwave/sessions/?page=1&page_size=50

previous_page_uri

string | null

URI for the previous page

Example: null

ResourceListResponse

ResourceResponse[]

uri

string

Current request URI

Example: /v1/chatterwave/resources/

page

integer

Current page number

Example: 0

page_size

integer

Results per page

Example: 50

first_page_uri

string

URI for the first page

Example: /v1/chatterwave/resources/?page=0&page_size=50

next_page_uri

string | null

URI for the next page

Example: /v1/chatterwave/resources/?page=1&page_size=50

previous_page_uri

string | null

URI for the previous page

Example: null

Error

error

string · required

Error code. Possible values:

not_found - Resource not found
invalid_input - Invalid input data
validation_error - Validation failed
insufficient_balance - Account balance too low
free_trial_exceeded - Free trial limit reached
invalid_recipient_count - Must have 1-25 recipients
mutually_exclusive_fields - Cannot provide both message and resource_id
business_rule_violation - Business rule check failed
external_service_error - Upstream service unavailable

Example: not_found

message

string · required

Human-readable error description

Example: DID not found