Managing Calls

After uploading an audio file using the /upload/request endpoint, you must create a Call record to trigger the AI processing.

[!IMPORTANT] You must first upload the audio file to get the fileKey. This fileKey is required for the recordingUrl field in the create call request. See Uploading Audio Guide

Create a Call

Endpoint: POST /calls/create

This endpoint links your uploaded audio to a call record and starts the transcription pipeline.

curl https://api.comswise.in/v1/calls/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callId": "unique-internal-id-123",
    "groupingId": "ticket-9876",
    "status": "completed",
    "startTime": "2024-02-28T10:30:00Z",
    "recordingUrl": "org_123/uploads/uuid.wav"
  }'

import requests

url = "https://api.comswise.in/v1/calls/create"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "callId": "unique-internal-id-123",
    "groupingId": "ticket-9876",
    "status": "completed",
    "startTime": "2024-02-28T10:30:00Z",
    "recordingUrl": "org_123/uploads/uuid.wav" # fileKey from upload step
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const url = 'https://api.comswise.in/v1/calls/create';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};
const payload = {
  callId: 'unique-internal-id-123',
  groupingId: 'ticket-9876',
  status: 'completed',
  startTime: '2024-02-28T10:30:00Z',
  recordingUrl: 'org_123/uploads/uuid.wav' // fileKey from upload step
};

axios.post(url, payload, { headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Request Body

Field	Type	Required	Description
`callId`	`string`	Yes	Your unique identifier for the call (e.g., from Twilio/Plivo).
`startTime`	`string`	Yes	ISO 8601 UTC timestamp.
`endTime`	`string`	No	ISO 8601 UTC timestamp.
`status`	`string`	No	`completed` (default) or `in-progress`.
`recordingUrl`	`string`	Conditional	URL or R2 key of the audio file. Required if status is `completed`. Key must valid in your R2 bucket.
`from`	`string`	Conditional	Caller's phone number. Format: E.164 (e.g., `+15550000000`). Required if `groupingId` is missing.
`to`	`string`	Conditional	Recipient's phone number. Format: E.164. Required if `groupingId` is missing.
`direction`	`string`	No	`inbound`, `outbound`, or `unknown`. Defaults to `unknown`.
`groupingId`	`string`	No	External ID (e.g. Ticket ID) to group messages into a single thread. If provided, `from`/`to` are optional.

Threading Logic: The system groups related calls/messages into a single conversation thread. You can control this grouping explicitly by providing a groupingId (e.g., your Ticket ID). If groupingId is not provided, the system will automatically group calls based on the combination of from and to numbers.

Example Request

{
  "callId": "unique-ref-123",
  "groupingId": "ticket-9876",
  "direction": "inbound",
  "status": "completed",
  "startTime": "2023-10-27T10:00:00Z",
  "recordingUrl": "org_xxxx/uploads/audio.wav"
}

Update a Call

Update an existing call, for example, to add the recording URL after the call is completed.

Endpoint: PATCH /calls/{id}

Where {id} is the unique system ID returned in the response of the create call request.

Request Body

Field	Type	Description
`recordingUrl`	`string`	Updated URL or R2 key of the audio file. Required if updating status to `completed`.
`status`	`string`	Updated status (e.g., `completed`).

Example Request

curl -X PATCH https://api.comswise.in/v1/calls/j976yz9yr5t5r40xs5xj4j7h017wx17r \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "recordingUrl": "org_123/uploads/new-file.wav"
  }'

Managing Calls

Create a Call

Request Body

Example Request

Update a Call

Request Body

Example Request

On this page