Backend API Reference

This page documents the server-side REST API for creating voice calls. Use this API from your backend server to implement the Server-Side Initiation flow.

Overview

The Backend API allows your server to create calls on behalf of your users and check their status, returning a signed URL that the client can use to connect securely without exposing your API key.

Authentication

All API requests require authentication using your API key in the X-Api-Key header.

X-Api-Key: your-api-key-here

Create Call

Creates a new voice call and returns connection credentials.

Important: You only need to make one POST request to create a call. The signedUrl returned in the response is immediately usable by the client-side SDK.

Endpoint

POST /v2/calls

Headers

Header	Value	Required
Content-Type	application/x-www-form-urlencoded multipart/form-data application/json	Yes
X-Api-Key	Your API key	Yes

Request Body

The API accepts URL-encoded form data, multipart form data, or JSON. When using form data (URL-encoded or multipart) and a parameter is an object, encode it as a JSON string.

Parameters:

Parameter	Type	Description	Required	Example
character	String or Object	Character identifier (e.g., "github:partner/character") OR custom character object	Yes	See below
call_time_limit_seconds	String	Maximum call duration in seconds	Yes	"3600"
on_completion_webhook	String	URL to receive webhook when call completes	No	"https://your-domain.com/webhook"
character_params	Object	Dictionary of parameters that will be used in template rendering in case if the character is created in Character Editor ("github:..."). Same as in Messages API v2 (legacy).	No

Character Parameter

You can specify a character in two ways:

Option 1: Character Identifier (String)

github:partner/character

Option 2: Custom Character (Object)

{
  "description": "{\"name\": \"Assistant\", ...}",
  "personality": "You are a helpful assistant..."
}

When using a custom character:

• description must be a JSON string containing the character configuration
• personality must be a string containing the system prompt

See the character editor app for valid configuration examples

Response Format

Returns the same format as the Get Call Status response. The call will initially be in "starting" state.

Get Call Status

Retrieve the current status of an existing call.

Endpoint

GET /v2/calls/{call_id}

Headers

Header	Value	Required
X-Api-Key	Your API key	Yes

Response Format

The API returns different response formats depending on the call state:

Example: Starting Call

{
  "data": {
    "id": "/v2/calls/3267",
    "character": "github:partner/character",
    "state": "starting",
    "available_endpoints": [],
    "duration": {
      "call_seconds": null,
      "server_runtime_seconds": null
    },
    "signedUrl": "https://backend.funtimewithaisolutions.com/v2/calls/3267?signature=xyz",
    "created_at": "2025-09-24T22:36:43.000000Z",
    "updated_at": "2025-09-24T22:36:43.000000Z"
  }
}

Example: Ongoing Call

{
  "data": {
    "id": "/v2/calls/3267",
    "character": "github:partner/character",
    "state": "ongoing",
    "available_endpoints": [...],
    "duration": {
      "call_seconds": null,
      "server_runtime_seconds": null
    },
    "signedUrl": "https://backend.funtimewithaisolutions.com/v2/calls/3267?signature=xyz",
    "created_at": "2025-09-24T22:36:43.000000Z",
    "updated_at": "2025-09-24T22:36:45.000000Z"
  }
}

Example: Completed Call

{
  "data": {
    "id": "/v2/calls/3267",
    "character": "github:partner/character",
    "state": "completed",
    "available_endpoints": [],
    "duration": {
      "call_seconds": 4,
      "server_runtime_seconds": 6
    },
    "signedUrl": "https://backend.funtimewithaisolutions.com/v2/calls/3267?signature=xyz",
    "created_at": "2025-09-24T22:36:43.000000Z",
    "updated_at": "2025-09-24T22:36:55.000000Z"
  }
}

Response Fields

Field	Type	Description
id	String	Unique call identifier
character	String	Character used for the call (null if character is custom)
state	String	Call state: "starting", "ongoing", "completed", or "error"
available_endpoints	Array	SDK-only field: WebSocket endpoints for connection (populated when state is "ongoing")
duration.call_seconds	Number/null	Actual conversation duration in seconds (available when completed)
duration.server_runtime_seconds	Number/null	Total server runtime in seconds (available when completed)
signedUrl	String	Most Important: Signed URL for client-side SDK connection
created_at	String	Call creation timestamp
updated_at	String	Last update timestamp

Get Call Transcript

Retrieve the conversation transcript for a completed call.

Endpoint

GET /v2/calls/{call_id}/transcript

Headers

Header	Value	Required
X-Api-Key	Your API key	Yes

Response Format

Example: Transcript Available

{
  "data": {
    "available": true,
    "transcript": [
      {
        "text": "Hello, how can I help you today?",
        "originator": "bot"
      },
      {
        "text": "I have a question about your service.",
        "originator": "user"
      },
      {
        "text": "Of course! I'd be happy to help. What would you like to know?",
        "originator": "bot"
      }
    ]
  }
}

Example: Transcript Not Available

{
  "data": {
    "available": false
  }
}

Response Fields

Field	Type	Description
available	Boolean	Whether transcript data is available
transcript	Array	Array of messages (only present when available is true)
transcript[].text	String	The message content
transcript[].originator	String	Who sent the message: "bot" or "user"

Notes

• Transcripts are only available after a call has completed.
• If a call ended unexpectedly or no conversation occurred, available will be false.

Webhooks

Webhooks allow you to receive notifications when calls complete. Include the on_completion_webhook parameter when creating a call to receive a webhook notification upon completion.

Behavior

When a call completes, a POST request is sent to your webhook URL:

• Payload: The payload is the same as the Get Call Status response for a completed call.
• HTTPS Required: Webhook URLs must use HTTPS with valid SSL certificates.
• Response Code: Your endpoint must return HTTP 200 for successful processing.
• Timeout: Webhook requests timeout after 30 seconds.
• Retries: Failed webhooks are retried up to 5 times with exponential backoff.

Please note that you're responsible for authentication of the webhook.

Call Time Limits

Call time limits automatically end calls after a specified duration. Include the call_time_limit_seconds parameter when creating a call to set a maximum duration in seconds.

Behavior

Calls are automatically terminated when the time limit is reached.

Error Handling

HTTP Status Codes

Status	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Response Format

{
  "error": {
    "code": "INVALID_CHARACTER",
    "message": "Character not found or not accessible"
  }
}

Next Steps

• Client Integration: See SDK Reference for using the returned signedUrl.
• Complete Example: Check Quick Start for end-to-end implementation.