Skip to main content

​
Endpoint

POST https://video.apifycloud.io/api/calls

​
Authentication

Widget key required. Provide appId and widgetKey via one of:
  • Headers: X-App-Id and X-Widget-Key
  • Query params: ?appId=...&widgetKey=...
  • Body: { "appId": "...", "widgetKey": "..." }

​
Request body

All fields are optional. Sending an empty body (or no body at all) creates a call with default settings.
FieldTypeDescription
presetIdstringPreset configuration to use. Falls back to the app’s active preset.
titlestringHuman-readable title for the call.
descriptionstringDescription or notes for the call.
metadataobjectFree-form JSON metadata attached to the call record.
hostNamestringDefault display name for the host. Overrides the preset default.
guestNamestringDefault display name for the guest. Overrides the preset default.
recordOnStartbooleanWhen true, recording starts automatically when the meeting begins. Overrides the preset setting.
genesysobjectGenesys Cloud context (see below). Also accepted via query params.

​
Genesys fields

FieldTypeDescription
conversationIdstringGenesys conversation ID
gcHostOriginstringGenesys Cloud host origin
gcTargetEnvstringGenesys target environment
gcLangTagstringLanguage tag (e.g. en-us)
gcUsePopupAuthbooleanUse popup-based authentication

​
Response

{
  "ok": true,
  "data": {
    "callId": "uuid",
    "hostJoinUrl": "https://video.apifycloud.io/c/{callId}?role=agent&appId=...&widgetKey=...",
    "guestJoinUrl": "https://video.apifycloud.io/c/{callId}",
    "joinUrl": "https://video.apifycloud.io/c/{callId}",
    "agentJoinUrl": "https://video.apifycloud.io/c/{callId}?role=agent&appId=...&widgetKey=...",
    "previewEnabled": true,
    "title": "string or absent",
    "description": "string or absent",
    "metadata": {}
  }
}
FieldDescription
callIdUnique identifier for the created call.
hostJoinUrlURL for the host/agent to join the call. Includes authentication params.
guestJoinUrlURL for the guest/participant to join the call.
joinUrlAlias for guestJoinUrl (backward compatibility).
agentJoinUrlAlias for hostJoinUrl (backward compatibility).
titleEchoed back when provided in the request.
descriptionEchoed back when provided in the request.
metadataEchoed back when provided in the request.

​
Errors

  • 401 missing or invalid appId/widgetKey
  • 500 internal server error

​
Examples

​
Minimal call

curl -X POST "https://video.apifycloud.io/api/calls" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: {appId}" \
  -H "X-Widget-Key: {widgetKey}"

​
Call with metadata and config

curl -X POST "https://video.apifycloud.io/api/calls" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: {appId}" \
  -H "X-Widget-Key: {widgetKey}" \
  -d '{
    "title": "Support Session #1234",
    "description": "Customer onboarding walkthrough",
    "metadata": { "ticketId": "T-1234", "priority": "high" },
    "hostName": "Sarah (Support)",
    "guestName": "John",
    "recordOnStart": true,
    "presetId": "my-preset"
  }'