Skip to main content
Realtime

Create a conversation

Create a conversation for realtime voice and text interactions and background work events.

Realtime is currently in beta. API definitions, event structures, and behavior may change. Monitor documentation updates and validate compatibility before using it in production.
POST /api/v1/forward/realtime/conversations

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyYesAn application-generated identifier for the create operation. It must be 1–256 bytes with no leading or trailing whitespace; a UUID is recommended. Reuse the same value and request body when retrying the same operation.

Request body

ParameterTypeRequiredDescription
identity_idstringYesID of an enabled Identity accessible within the current authentication scope. It must be 1–128 characters with no leading or trailing whitespace or control characters.
template_idstringYesID of a Template accessible within the current authentication scope. It must be 1–128 characters with no leading or trailing whitespace or control characters.
titlestring or nullNoDefaults to null. After trimming, it must contain 1–256 characters and no control characters.
metadataobject or nullNoDefaults to {}; null is treated as {}. The normalized stored text must not exceed 16 KiB and must not contain U+0000.
configobjectNoRealtime configuration for the conversation. When omitted, the service resolves the default configuration. null is not accepted.
config.audioobjectNoAudio configuration.
config.audio.outputobjectNoOutput audio configuration.
config.audio.output.voicestringNoPreset voice identifier. Only the values in the following table are accepted. The value is fixed after creation and cannot be changed.

Preset voices

voiceName
longanqianDefault
longanlingxinLongan Lingxin
longanlingxiLongan Lingxi
longanxiaoxinLongan Xiaoxin
longanlufengLongan Lufeng

Example request

IDEMPOTENCY_KEY="$(uuidgen)"

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/realtime/conversations" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "identity_id": "idn_xxx",
    "template_id": "tmpl_xxx",
    "title": "Project analysis",
    "metadata": {"source": "desktop"},
    "config": {
      "audio": {
        "output": {
          "voice": "longanlingxin"
        }
      }
    }
  }'

Example response

HTTP 201 Created 
{
  "id": "conv_xxx",
  "type": "voice.conversation",
  "status": "ready",
  "title": "Project analysis",
  "metadata": {
    "source": "desktop"
  },
  "config": {
    "audio": {
      "output": {
        "voice": "longanlingxin"
      }
    }
  },
  "created_at": "2026-08-31T02:00:00Z",
  "updated_at": "2026-08-31T02:00:01Z"
}

Response fields

FieldTypeDescription
idstringConversation ID.
typestringAlways voice.conversation.
statusstringready when creation succeeds.
titlestring or nullConversation title.
metadataobjectBusiness metadata.
configobjectComplete effective configuration resolved and persisted by the service.
config.audio.output.voicestringOutput voice fixed for the conversation.
created_atstringCreation time in RFC 3339 format.
updated_atstringUpdate time in RFC 3339 format.

Idempotent retries

  • The same Idempotency-Key and request body replay the first create result.
  • A replayed response includes Idempotency-Replayed: true.
  • Using the same Idempotency-Key with a different request body returns 409 idempotency_conflict.
  • If the initial request is still being processed, the service returns 409 idempotency_key_in_progress. Use the interval in Retry-After before retrying.

Errors

HTTPCodeTrigger
400invalid_request, invalid_identity_id, invalid_template_id, invalid_title, invalid_metadataThe request parameters are invalid.
400invalid_voiceconfig.audio.output.voice is not supported.
400invalid_idempotency_keyThe idempotency header is missing or invalid.
401authentication_required, gateway TOKEN_INVALIDThe PAT or SAT is invalid or expired, or a Service Account Key was used directly.
403permission_error, identity_mismatchThe SAT is not bound to an available Workspace, or an Identity-scoped SAT specifies a different Identity.
404identity_not_foundThe Identity was not found within the current authentication scope.
409idempotency_conflictThe same key cannot be used for different requests.
409idempotency_key_in_progressA request with the same key is still being processed. See Retry-After for the retry interval.
409conversation_not_ready, conversation_initialization_conflictThe conversation is not ready or initialization conflicts.
422identity_disabledThe Identity is disabled.
422conversation_initialization_failedConversation initialization failed.
500conversation_persistence_error, conversation_state_invalid, template_config_read_failed, internal_errorAn internal service error occurred.
502forward_unavailable, forward_protocol_errorA dependent service failed.
503idempotency_unavailableThe service is temporarily unavailable.

Connect to a conversation

Create a session

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Create a conversation - Qoder