Skip to content
mondochat

Start a call

POST
/v1/calls
curl --request POST \
  --url https://app.mondochat.io/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "conversation_id": "0199d6a0-2000-7000-8000-000000000001", "video": true }'

Starts a call in a conversation and rings the other user. Takes a session token. calls.enabled, the call policy flag, safety and bans are checked. Answers 409 conflict when the caller already has an open call, and 409 busy when the callee is in a ringing or active call or was rung in the last 45 seconds. The call is ringing, a call_invite card is posted, the callee is told, and the response carries what the caller needs to join the Agora channel. See https://docs.mondochat.io/guides/calls/.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
StartCall

The conversation to call in.

object
conversation_id
required
Conversation Id

The conversation to call in.

string format: uuid
video
Video

How the callee’s client rings.

boolean

Responses

Section titled “Responses”

201

Section titled “201”

Successful Response

Media typeapplication/json
CallJoin

What a client needs to join the call’s Agora channel.

object
agora_app_id
required
Agora App Id

The Agora app id to join with.

string
call
required
Call

The call.

object
answered_at
Any of:
string format: date-time
callee_id
required
Callee Id

The user who is called.

string format: uuid
caller_id
required
Caller Id

The user who started the call.

string format: uuid
conversation_id
required
Conversation Id

The conversation the call belongs to.

string format: uuid
end_reason
Any of:
string
ended_at
Any of:
string format: date-time
id
required
Id

The call’s id.

string format: uuid
started_at
required
Started At

When the call was started.

string format: date-time
state
required
State

ringing until answered, then active; missed, declined and busy end it unanswered, ended after it was answered.

string
Allowed values: ringing active ended missed declined busy
video
Video

How the callee’s client rings; it changes nothing else.

boolean
channel
required
Channel

The Agora channel of the call.

string
expires_at
required
Expires At

When the token stops working.

string format: date-time
peer_uid
required
Peer Uid

The other participant’s uid. React only to this uid in the channel.

integer
rtc_token
required
Rtc Token

The Agora token for this channel and uid.

string
uid
required
Uid

The caller’s numeric Agora uid.

integer

Example 

{
  "agora_app_id": "0123456789abcdef0123456789abcdef",
  "call": {
    "callee_id": "0199d6a0-1000-7000-8000-000000000002",
    "caller_id": "0199d6a0-1000-7000-8000-000000000001",
    "conversation_id": "0199d6a0-2000-7000-8000-000000000001",
    "id": "0199d6a0-5000-7000-8000-000000000001",
    "started_at": "2026-11-01T09:30:00Z",
    "state": "ringing",
    "video": true
  },
  "channel": "0199d6a0-5000-7000-8000-000000000001",
  "expires_at": "2026-11-01T13:30:00Z",
  "peer_uid": 1002,
  "rtc_token": "example-rtc-token",
  "uid": 1001
}

4XX

Section titled “4XX”

Problem

Media typeapplication/problem+json

An RFC 9457 problem: the body of every error answer.

object
code
required

The stable error code to branch on, such as policy_denied.

string
detail

What went wrong this time, when there is more to say.

string | null
errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object
loc

The path to the field.

array
msg

What is wrong with it.

string
instance

The path of the request.

string
reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string
status
required

The HTTP status code.

integer
title
required

A short summary of the problem.

string
type
required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example 

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}