Create a call

Create a new call with recording, transcript, agents, and customers

POST /v1/call

JavaScript

JavaScript

import Roark from '@roarkanalytics/sdk';

const client = new Roark({
  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
});

const call = await client.call.create({
  callDirection: 'INBOUND',
  interfaceType: 'PHONE',
  recordingUrl: 'https://example.com',
  startedAt: 'startedAt',
});

console.log(call.data);

200

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "RINGING",
    "callDirection": "INBOUND",
    "startedAt": "2024-01-15T10:00:00Z",
    "agents": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "endpoint": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "environment": "<string>",
          "phoneNumberE164": "<string>"
        }
      }
    ],
    "customers": [
      {
        "phoneNumberE164": "<string>",
        "label": "<string>"
      }
    ],
    "createdAt": "<string>",
    "externalId": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Call creation payload. Supports singular (agent/customer) or plural (agents/customers) formats.

recordingUrl · string<uri> · required

URL of source recording (must be an accessible WAV, MP3, MP4, or OGG file). Can be a signed URL.

startedAt · string · required

When the call started (ISO 8601 format)

interfaceType · enum<string> · required

Interface type of the call (PHONE or WEB)

Available options: PHONE, WEB

callDirection · enum<string> · required

Direction of the call (INBOUND or OUTBOUND)

Available options: INBOUND, OUTBOUND

stereoRecordingUrl · string<uri>

URL of source stereo recording. Must be accessible. Can be a signed URL. Supported formats: WAV, MP3, MP4, OGG.

endedStatus · enum<string>

High-level call end status, indicating how the call terminated

Available options: PARTICIPANTS_DID_NOT_SPEAK, AGENT_DID_NOT_ANSWER, AGENT_DID_NOT_SPEAK, AGENT_STOPPED_SPEAKING, AGENT_ENDED_CALL, AGENT_TRANSFERRED_CALL, AGENT_BUSY, AGENT_ERROR, CUSTOMER_ENDED_CALL, VOICE_MAIL_REACHED, SILENCE_TIME_OUT, PHONE_CALL_PROVIDER_CONNECTION_ERROR, CUSTOMER_DID_NOT_ANSWER, CUSTOMER_DID_NOT_SPEAK, CUSTOMER_STOPPED_SPEAKING, CUSTOMER_BUSY, DIAL_ERROR, MAX_DURATION_REACHED, UNKNOWN

transcript · object[]

List of transcript entries made during the call

Option 1

Option 2

Show child attributes

toolInvocations · object[]

List of tool invocations made during the call

Show child attributes

properties · object

Custom properties to include with the call. These can be used for filtering and will show in the call details page

Show child attributes

vapiCallId · string<uuid>

The Vapi call ID (UUID) to link this call with OpenTelemetry trace data from Vapi. Used for matching calls with OTEL traces.

livekitRoomId · string

The LiveKit Cloud room ID to link this call with OpenTelemetry trace data from LiveKit. Used for matching calls with OTEL traces.

Maximum string length: 255

externalId · string

A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this call with OpenTelemetry traces. Set the same value as a roark.external_id span or resource attribute on your traces and the matching trace will be linked automatically. Must be unique within a project.

Maximum string length: 255

agent · object

Single agent participating in the call. Use this for simpler API when you have only one agent.

Option 1

Option 2

Option 3

Show child attributes

agents · object[]

Agents participating in the call. Each agent requires identification and prompt information.

Agent participating in the call with their endpoint and prompt

Option 1

Option 2

Option 3

Show child attributes

customer · object

Single customer participating in the call. Use this for simpler API when you have only one customer.

Show child attributes

customers · object[]

Customers participating in the call.

Show child attributes

Response

200

application/json

Call created successfully

data · CallCreateResponse · object · required

Response after creating a call

Show child attributes