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 access token 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 "Authorization: Bearer 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": "[phone]"             # 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", // Unique identifier - save this!
  "firstName": "Test",
  "lastName": "User",
  "primaryPhone": "[phone]",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

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 "Authorization: Bearer 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 "Authorization: Bearer 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 "Authorization: Bearer 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.

Note: 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 "Authorization: Bearer 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": ["[phone]"],               # Caller ID numbers (must be yours)
    "retryStrategy": {
      "type": "none"                            # No retries for this test
    }
  }'

The didPool contains the phone numbers that will show up as the caller ID. Make sure you're using numbers assigned to your account.

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 "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "executionId": "execution-uuid-here" // Use this 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 "Authorization: Bearer YOUR_API_KEY"

You'll see the status and progress counters:

{
  "id": "execution-uuid",
  "status": "running", // Current state: pending, running, completed, failed
  "totalContacts": 1, // Total contacts in the audience
  "contactsCompleted": 0, // Successfully called
  "contactsFailed": 0, // Failed calls
  "contactsPending": 1, // Waiting to be called
  "contactsInProgress": 0 // Currently being called
}

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 "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "[phone]",              # Your 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