Making Your First Call

Let’s walk through the complete process of making an automated call with Gomobile. By the end of this guide, you’ll have created a contact, built an audience, set up a simple flow, and launched a program that actually places a call.

Before you start

Make sure you have:

An authenticated session (see Authentication)
Your API key ready
A phone number you can call for testing

We’ll use curl commands throughout, but you can adapt these to any HTTP client.

Step 1: Create a contact

First, add the person you want to call:

# Create a new contact in your Gomobile account
curl -X POST https://api.gomobile.ma/api/contact \
  -H "x-api-key: YOUR_API_KEY" \    # Your API key for authentication
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test",                        # Contact's first name
    "lastName": "User",                         # Contact's last name
    "primaryPhone": "+212612345678"             # Phone number to call (with country code)
  }'

Save the id from the response—you’ll need it in the next step.

{
  "id": "contact-uuid-here",
  "firstName": "Test",
  "lastName": "User",
  "primaryPhone": "+212612345678",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Save the id value - you’ll need it for the next steps.

Step 2: Create an audience

Audiences are groups of contacts. Even for a single contact, you need an audience:

# Create an audience to group contacts for your campaign
curl -X POST https://api.gomobile.ma/api/audience \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Audience",                    # A descriptive name for this group
    "description": "For testing my first call"  # Optional description
  }'

Save the audience id from the response.

Step 3: Add the contact to the audience

Link your contact to the audience:

# Add one or more contacts to an existing audience
curl -X POST https://api.gomobile.ma/api/audience/AUDIENCE_ID/add-contacts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": ["CONTACT_ID"]                  # Array of contact IDs to add
  }'

Step 4: Create a flow

Flows define what happens during a call. Here’s a simple flow that dials the contact, plays a greeting message, and hangs up:

# Create a call flow that defines the call logic
curl -X POST https://api.gomobile.ma/api/flows \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Greeting Flow",
    "description": "A basic flow that plays a welcome message",
    "graph": {
      "startNodeId": "dial-1",                  # Which node to start with
      "nodes": [
        {
          "id": "dial-1",                       # Unique node identifier
          "type": "dial",                       # Node type: initiates the call
          "label": "Dial Contact",
          "config": {
            "timeout": 30000,                   # Wait 30 seconds for answer
            "enableAMD": false                  # Answering Machine Detection off
          },
          "outputs": {                          # Define what happens next based on outcome
            "onAnswer": "play-1",               # If answered → play the greeting
            "onNoAnswer": "hangup-1",           # If no answer → end the call
            "onBusy": "hangup-1"                # If busy → end the call
          }
        },
        {
          "id": "play-1",                       # Greeting node
          "type": "play",                       # Node type: plays audio to the caller
          "label": "Play Greeting",
          "config": {
            "audioId": "AUDIO_ID"               # ID of your pre-recorded audio file
          },
          "outputs": {
            "onEnd": "hangup-1"                 # After playing → end the call
          }
        },
        {
          "id": "hangup-1",
          "type": "hangup",                     # Node type: ends the call
          "label": "End Call",
          "config": {
            "reason": "Call completed",
            "hangupType": "normal"
          }
        }
      ]
    }
  }'

Save the flow id.

Replace AUDIO_ID with the ID of your pre-recorded audio file. You can upload audio files via the Audio Management API. See the Designing Call Flows guide for more advanced examples with menus and user input handling.

Step 5: Create a program

Programs tie everything together. They specify which audience to call, which flow to use, and when to execute:

# Create a program (campaign) that orchestrates calls
curl -X POST https://api.gomobile.ma/api/programs \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Campaign",
    "audienceId": "AUDIENCE_ID",                # Which contacts to call
    "flowId": "FLOW_ID",                        # Which flow to execute
    "startAt": "2025-01-20T10:00:00Z",          # When to start (ISO 8601 format)
    "didPool": ["DID_ID"],                      # Caller ID DID UUIDs (must belong to your org)
    "retryStrategy": {
      "type": "none"                            # No retries for this test
    }
  }'

The didPool contains DID UUIDs used as caller ID. Use a DID allocated to your account (see GET /dids/available in the API reference).

Step 6: Launch the program

Programs start in draft status. To execute them, launch an execution:

# Launch the program to start making calls
curl -X POST https://api.gomobile.ma/api/programs/PROGRAM_ID/launch \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "executionId": "execution-uuid-here"
}

Use this executionId to track progress.

Step 7: Monitor the execution

Check how your execution is progressing:

# Get the current status of your program execution
curl -X GET https://api.gomobile.ma/api/program-executions/EXECUTION_ID \
  -H "x-api-key: YOUR_API_KEY"

You’ll see the status and progress counters:

{
  "id": "execution-uuid",
  "status": "running",
  "totalContacts": 1,
  "contactsCompleted": 0,
  "contactsFailed": 0,
  "contactsPending": 1,
  "contactsInProgress": 0
}

The fields show: status (pending/running/completed/failed), totalContacts, contactsCompleted, contactsFailed, contactsPending, and contactsInProgress.

Alternative: Ad-hoc calls

If you don’t need the full program infrastructure, you can make one-off calls directly:

# Make a single call without creating a program
curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "didId": "DID_ID",                          # Your DID UUID caller ID
    "contactId": "CONTACT_ID",                  # Who to call
    "flowId": "FLOW_ID",                        # Which flow to use
    "retry": { "type": "none" }                 # No retries
  }'

This is useful for testing flows or making individual calls outside of a campaign.

What’s next?

You’ve made your first call! Here’s where to go from here:

Core Concepts

Understand how all the pieces fit together.

Designing Call Flows

Build more sophisticated call logic with audio playback.

Retry Strategies

Handle failed calls gracefully.

Audio Management

Upload and manage your audio files.

Introduction

Getting Started

Core Concepts

Features

Agent Studio

Guides

Making Your First Call

Before you start

Step 1: Create a contact

Step 2: Create an audience

Step 3: Add the contact to the audience

Step 4: Create a flow

Step 5: Create a program

Step 6: Launch the program

Step 7: Monitor the execution

Alternative: Ad-hoc calls

What’s next?

Core Concepts

Designing Call Flows

Retry Strategies

Audio Management

​Before you start

​Step 1: Create a contact

​Step 2: Create an audience

​Step 3: Add the contact to the audience

​Step 4: Create a flow

​Step 5: Create a program

​Step 6: Launch the program

​Step 7: Monitor the execution

​Alternative: Ad-hoc calls

​What’s next?

Core Concepts

Designing Call Flows

Retry Strategies

Audio Management

Before you start

Step 1: Create a contact

Step 2: Create an audience

Step 3: Add the contact to the audience

Step 4: Create a flow

Step 5: Create a program

Step 6: Launch the program

Step 7: Monitor the execution

Alternative: Ad-hoc calls

What’s next?