Skip to main content

Calls

All requests to the Fonema API must be sent to the base endpoint: https://api.fonema.ai/

Start a call​

Endpoint​

POST /v2/initiate-call

Starts an automated phone call using one of your agents.

Request Body​

{
    "agentId": "Ales-VLP5QKP1",
    "customer": {
        "name": "Juan Perez",
        "phoneNumber": "+525581354511",
        "email": "juan.perez@example.com"
    },
    "delay": 30,
    "variableValues": {
        "montoDeuda": "30000",
        "numeroReferencia": "REF-12345"
    }
}

Parameters​

agentId (string, required)​

  • Description: Unique identifier of the agent that will place the call.
  • How to get it: Find this value in your Fonema dashboard, under each agent name.
  • Example: "Ales-VLP5QKP1"

Agent ID location

customer (object)​

Information about the customer receiving the call:

  • phoneNumber (string, required): Phone number in E.164 format (including country code).
  • name (string, optional): Full customer name.
  • email (string, optional): Customer email address.

delay (integer, optional)​

  • Description: Delay in seconds before starting the call.

variableValues (object, optional)​

  • Description: Custom variables used during the call.
  • Format: Key-value pairs where each key matches a variable defined in your agent.

Request Example​

curl -X POST "https://api.fonema.ai/v2/initiate-call" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "Ales-VLP5QKP1",
    "customer": {
        "name": "Maria Garcia",
        "phoneNumber": "+525599999999",
        "email": "maria.garcia@example.com"
    },
    "delay": 45,
    "variableValues": {
        "montoDeuda": "15000",
        "producto": "Gold Credit Card"
    }
}'

Important considerations​

  • Phone format: Always include country code (e.g., +52 for Mexico).
  • Required variables: Make sure to include every variable your agent expects.