Ad-hoc Calls

Request and manage individual calls with retry strategies.

Base path: /call-requests

Types

Type Definitions

// ============================================
// RETRY STRATEGY
// ============================================

type RetryStrategy =
  | { type: 'none' }
  | { type: 'fixed-delay'; delay: number; maxRetries: number }  // delay in ms
  | { type: 'scheduled'; dates: string[] };  // ISO date strings

// ============================================
// REQUEST TYPES
// ============================================

interface RequestCallDto {
  /** DID UUID for outbound caller ID (from GET /dids/available) */
  didId: string;

  /** Contact being called (phone fetched from contact.primaryPhone) */
  contactId: string;

  /** Flow to execute during call */
  flowId: string;

  /** Retry strategy */
  retry: RetryStrategy;

  /** Optional: Schedule call for future execution (ISO date string) */
  startAt?: string;
}

// ============================================
// RESPONSE TYPES
// ============================================

interface CallRequestResult {
  /** UUID job ID for tracking and querying reports */
  jobId: string;

  /** Always 'queued' (execution happens async) */
  status: 'queued';
}

Request an ad-hoc call

Immediate execution:

curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": { "type": "none" }
}
'

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

With fixed-delay retry:

curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": {
    "type": "fixed-delay",
    "delay": 300000,
    "maxRetries": 3
  }
}
'

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Scheduled start:

curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": { "type": "none" },
  "startAt": "2025-12-17T10:00:00Z"
}
'

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Scheduled retry dates:

curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": {
    "type": "scheduled",
    "dates": [
      "2025-12-17T11:00:00Z",
      "2025-12-17T14:00:00Z"
    ]
  }
}
'

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Error Responses:

Code	Error	Description
400	`CallRequestValidationError`	Invalid request (missing fields, invalid format)
400	`InvalidRetryStrategyError`	Malformed retry strategy
400	`InvalidStartTimeError`	startAt is in the past
404	`FlowNotFoundError`	Flow does not exist
404	`DidNotFoundError`	DID not found
400	`DidNotActiveError`	DID is not active
400	`DidNotAccessibleError`	DID is not available to this organization
404	`ContactNotFoundError`	Contact does not exist or has no phone

Cancel a queued call

Notes:

No-op if call is already executing or completed
Only cancels calls in waiting or delayed state

DELETE /call-requests/550e8400-e29b-41d4-a716-446655440000
// Response 204 (no body)

Notes

organizationId is automatically injected from the authenticated user’s organization
Phone number is fetched from contact.primaryPhone. Caller ID is resolved from the DID UUID via GET /dids/available
jobId is a UUID that can be used to query reports via /call-report/:jobId
Priority is fixed at 3 for ad-hoc calls (configurable for program calls)
Program calls vs ad-hoc calls: This API is for ad-hoc (manual) calls. Program calls are initiated by the Program Orchestrator internally with retry: { type: 'none' } - the orchestrator manages retries externally via execution_contacts table to respect capacity limits and pause windows.

Introduction

Getting Started

Core Concepts

Features

Agent Studio

Guides

Types

Request an ad-hoc call

Cancel a queued call

Notes

​Types

​Request an ad-hoc call

​Cancel a queued call

​Notes

Types

Request an ad-hoc call

Cancel a queued call

Notes