ai_call_agent

Initiate an authorized outbound AI telephone call and return a call identifier immediately; completion and duration arrive asynchronously.

When to use

Use when an authorized agent must contact a customer by telephone for a lawful, consent-aware objective and retrieve a structured result later.

Selection guidance

Role: specialized. Use when an authorized agent must contact a customer by telephone for a lawful, consent-aware objective and retrieve a structured result later.

Use cases

• outbound AI call
• customer confirmation
• telephone follow-up

Access

• REST: POST https://api.rafidsystem.com/api/v1/voice/ai-call
• x402: POST https://api.rafidsystem.com/api/v1/x402/voice/ai-call
• MCP tool: ai_call_agent

Price: $0.30 USD per call. Payment options are deployment-configured; inspect /api/v1/payment-methods. Prices and payment semantics are unchanged from the canonical registry.

Related tools

• appointment_call_agent

Example input

{
  "phoneNumber": "+96891234567",
  "objective": "Confirm interest in a product demonstration.",
  "language": "en",
  "maxDurationSeconds": 300,
  "context": {
    "customerName": "Example Customer"
  }
}

Example output

{
  "callId": "call_example",
  "status": "queued",
  "answered": false,
  "durationSeconds": 0,
  "outcome": null,
  "summary": null,
  "nextAction": null,
  "structuredFacts": {},
  "transcript": [],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "completedAt": null
}

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "phoneNumber": {
      "type": "string",
      "pattern": "^\\+[1-9]\\d{7,14}$"
    },
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 2000
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "ar"
      ]
    },
    "maxDurationSeconds": {
      "default": 300,
      "type": "integer",
      "minimum": 1,
      "maximum": 3600
    },
    "context": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "safety": {
      "type": "object",
      "properties": {
        "consentNotice": {
          "type": "string",
          "maxLength": 500
        },
        "recording": {
          "default": false,
          "type": "boolean"
        },
        "transcription": {
          "default": false,
          "type": "boolean"
        },
        "timezone": {
          "type": "string",
          "maxLength": 100
        }
      },
      "required": [
        "recording",
        "transcription"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "phoneNumber",
    "objective",
    "language",
    "maxDurationSeconds"
  ],
  "additionalProperties": false
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "callId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "created",
        "queued",
        "dialing",
        "ringing",
        "answered",
        "in_progress",
        "completed",
        "no_answer",
        "busy",
        "rejected",
        "failed",
        "cancelled"
      ]
    },
    "answered": {
      "type": "boolean"
    },
    "durationSeconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "outcome": {
      "type": [
        "string",
        "null"
      ]
    },
    "summary": {
      "type": [
        "string",
        "null"
      ]
    },
    "nextAction": {
      "type": [
        "string",
        "null"
      ]
    },
    "structuredFacts": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "transcript": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "speaker": {
            "type": "string",
            "enum": [
              "agent",
              "customer"
            ]
          },
          "text": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
          }
        },
        "required": [
          "speaker",
          "text",
          "at"
        ],
        "additionalProperties": false
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
    },
    "completedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "callId",
    "status",
    "answered",
    "durationSeconds",
    "outcome",
    "summary",
    "nextAction",
    "structuredFacts",
    "transcript",
    "createdAt",
    "completedAt"
  ],
  "additionalProperties": false
}

Category: Voice / Communication · hierarchy: specialized · idempotent: no · side effects: yes