Frequently Asked Questions

Find answers to the most common questions about Gomobile.

---

Authentication & Access

How do I get an API key?

API keys are provisioned by the Gomobile team to ensure security and proper access control.

To request an API key:

1. Visit our API Key Request Form

2. Fill in your details and use case

3. Our team will review and provision your key within 24 hours

4. You'll receive your API key via secure email

Once you receive your key, store it securely and use it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

What authentication method does Gomobile use?

Gomobile uses API key-based authentication. Your API key is a long-lived credential that you include in every request:

Authorization: Bearer YOUR_API_KEY

Feature	API Key
Lifespan	Long-lived
Obtained via	Request from Gomobile team
Refresh needed	No
Best for	All API integrations

API keys are provisioned by our team. Request your API key to get started.

My API key stopped working. What happened?

Common reasons:

1. Expired - Your key may have an expiration date

2. Revoked - The key may have been revoked for security reasons

3. Wrong format - Ensure you're using Authorization: Bearer <your-key>

4. Typo - Double-check you're using the correct key

To resolve: Contact our support team and we'll help you verify your key status or provision a new one.

Can I have multiple API keys?

Yes! You can have multiple API keys for different purposes:

• Per environment: Separate keys for development, staging, and production

• Per integration: One key per third-party service

• Per team member: Individual keys for accountability

To request additional API keys, contact our team with your use case.

How do I rotate my API key safely?

Follow this sequence to avoid downtime:

1. Request a new key - Contact our team to provision a new API key

2. Receive your new key - We'll send it via secure email

3. Update your applications - Deploy the new key to your systems

4. Test - Verify everything works with the new key

5. Notify us - Let us know to revoke the old key

---

Contacts & Audiences

What's the difference between a contact and an audience?

Concept	Description
Contact	An individual person with a phone number and optional details (name, email, address, custom attributes)
Audience	A named group of contacts that can be targeted by a program

Think of contacts as rows in a database, and audiences as saved filters or segments. One contact can belong to multiple audiences.

Can a contact be in multiple audiences?

Yes! Contacts can belong to any number of audiences simultaneously. Add contacts to an audience using:

POST /audience/:id/add-contacts
{
  "contacts": ["contact-uuid-1", "contact-uuid-2"]
}

What phone number formats are accepted?

Phone numbers must be 3-20 characters. We recommend E.164 format:

+[country code][number]

Examples:

• ✅ [phone] (Morocco)

• ✅ [phone] (USA)

• ❌ 06-12-34-56-78 (spaces/dashes)

• ❌ 0612345678 (missing country code)

How do I import contacts in bulk?

Use the upsert endpoint to import multiple contacts at once:

POST /contact/upsert
{
  "data": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "primaryPhone": "[phone]"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "primaryPhone": "[phone]"
    }
  ]
}

Existing contacts (matched by phone number) are updated; new contacts are created.

Can I add custom fields to contacts?

Yes! First, define a custom attribute for your organization:

POST /custom-attributes
{
  "displayName": "Customer Tier",
  "type": "text"  // text, number, boolean, date, phone_number, email, url
}

Then include it when creating/updating contacts:

{
  "primaryPhone": "[phone]",
  "customAttributes": {
    "customer_tier": "gold"
  }
}

How do I remove a contact from all campaigns?

Two options:

1. Soft delete the contact: DELETE /contact/:id - Contact is marked as deleted but data is retained

2. Remove from specific audiences: Manage audience membership individually

Note: Deleting a contact doesn't cancel in-progress calls to that contact.

What happens to contacts when I delete an audience?

Contacts are NOT deleted. Only the audience grouping is removed. Contacts remain in your organization and can be added to other audiences.

---

Flows & Nodes

What's the difference between a flow and a program?

Concept	Purpose
Flow	Defines what happens during a call - the logic, audio, inputs, branching
Program	Defines when, who, and how - audience, schedule, retry strategy, pause windows

A flow is like a script; a program is like a scheduled performance of that script to a specific audience.

Can I reuse flows across multiple programs?

Yes! Flows are templates that can be used by many programs. Create the flow once, then reference its flowId in different programs targeting different audiences or schedules.

What happens if a flow has an error during execution?

Each node has an onError output you can configure. If an error occurs:

1. The flow follows the onError path if defined

2. Otherwise, it follows the default output if defined

3. If neither exists, the call is terminated with outcome failed

The error details are captured in the call report's flowExecution.executionPath.

How do I test a flow before launching?

Use the validate endpoint to check your flow without saving:

POST /flows/validate
{
  // Your flow definition
}

Response:

{
  "valid": true,
  "errors": []
}

You can also execute a single test call using POST /flows/execute with a test contact.

What node types are available?

Node	Purpose	Key Outputs
Dial	Places outbound call	onAnswer, onVoicemail, onNoAnswer, onBusy, onRejected, onError
Answer	Answers inbound call	onSuccess, onError
Play	Plays audio	onComplete, onError
DTMF	Collects keypad input	branches (by digit), onSuccess, onTimeout, onInvalid, onMaxRetries
Record	Records voice	onComplete, onTimeout, onError
Condition	Branches on logic	onTrue, onFalse, onError
Set Variable	Stores a value	onSuccess, onError
Hangup	Ends the call	None (terminal)

Can I branch logic based on caller input?

Yes! Use the DTMF node with branches:

{
  "type": "dtmf",
  "config": {
    "mode": "single_digit",
    "variable": "user_choice",
    "timeout": 10000
  },
  "outputs": {
    "branches": {
      "1": "sales-node",
      "2": "support-node",
      "3": "billing-node"
    },
    "onTimeout": "retry-node",
    "onInvalid": "invalid-input-node"
  }
}

How do I play dynamic content (name, amount)?

Use ValueSource references in your Play node:

{
  "type": "play",
  "config": {
    "audioItems": [
      { "type": "audioFile", "audioId": "welcome-audio-id" },
      {
        "type": "number",
        "value": { "source": "customAttribute", "attributeName": "balance" },
        "mode": "full",
        "language": "ar"
      }
    ]
  }
}

Sources available: variable, customAttribute, contactField.

---

Calls & Execution

Why didn't my call go through?

Check the call report (GET /call-report/:jobId) for the outcome field:

Outcome	Meaning
no_answer	Recipient didn't pick up (timeout reached)
busy	Line was busy
rejected	Recipient declined the call
failed	System error (check outcomeReason)
cancelled	Call was cancelled before completion

Also verify:

• Phone number format is correct

• DID pool has valid numbers

• Program status is active

What does "AMD" mean?

AMD = Answering Machine Detection

When enabled (enableAMD: true) on a Dial node, the system detects whether a human or voicemail answered:

• Human detected → Routes to onAnswer

• Machine detected → Routes to onVoicemail

This lets you play different messages or skip voicemails entirely.

How long does a call attempt last?

The dial timeout determines how long to wait for an answer. Default is 30 seconds (30000ms).

Configure it in your Dial node:

{
  "type": "dial",
  "config": {
    "timeout": 45000 // 45 seconds
  }
}

Can I schedule calls for a specific time?

Yes! Set startAt when creating a program:

POST /programs
{
  "name": "Morning Campaign",
  "startAt": "2025-12-20T09:00:00Z",
  "stopAt": "2025-12-20T18:00:00Z",  // optional end time
  ...
}

The program won't start calling until the scheduled time.

How do I stop a running campaign?

Two options:

1. Pause (can resume later):

   PATCH /program-executions/:id/pause

2. Cancel (permanent):

   DELETE /program-executions/:id

Note: Already-queued calls will complete; only pending contacts are affected.

What happens to pending calls when I pause a program?

• In-progress calls: Continue until they complete

• Queued calls: Will finish processing

• Pending contacts: Wait until you resume with PATCH /program-executions/:id/resume

The execution status changes to paused and no new contacts are pulled until resumed.

Can I call the same contact multiple times?

Yes, through retry strategies. If a call fails (no answer, busy, etc.), the system can automatically retry based on your configuration:

• fixed_delay: Retry after X minutes

• scheduled: Retry at specific times

See the Retry Strategies section below.

---

Retry Strategies

How many times will Gomobile retry a failed call?

It depends on your retry strategy:

• none: No retries (1 attempt total)

• fixed_delay: Up to maxRetries additional attempts

• scheduled: Number of dates in retryDates array

Example with 3 retries (4 total attempts):

{
  "type": "fixed_delay",
  "delayMinutes": 30,
  "maxRetries": 3
}

What triggers a retry?

Retries are triggered when a call doesn't reach a successful outcome:

• ✅ completed - No retry (success)

• 🔄 no_answer - Retry

• 🔄 busy - Retry

• 🔄 rejected - Retry

• 🔄 voicemail - Retry (configurable)

• ❌ failed - Retry (system error)

How long between retries?

For fixed_delay strategy, set delayMinutes:

{
  "type": "fixed_delay",
  "delayMinutes": 30, // Wait 30 minutes between attempts
  "maxRetries": 2
}

For scheduled strategy, specify exact times:

{
  "type": "scheduled",
  "retryDates": ["2025-12-17T14:00:00Z", "2025-12-18T09:00:00Z"]
}

Can I retry at specific times?

Yes! Use the scheduled retry strategy:

{
  "type": "scheduled",
  "retryDates": [
    "2025-12-17T14:00:00Z", // First retry
    "2025-12-18T09:00:00Z", // Second retry
    "2025-12-19T09:00:00Z" // Third retry
  ]
}

Each date is an ISO 8601 timestamp for when the retry should occur.

Do retries respect pause windows?

Yes. If a retry is scheduled during a pause window, it waits until the pause window ends before attempting the call.

---

Pause Windows & Scheduling

What's a pause window?

A pause window is a time range when calls should NOT be made. Use them for:

• Lunch breaks

• Outside business hours

• Holidays

• Weekends

During a pause window, the system stops pulling new contacts. Already-queued calls complete, but no new calls start.

Can I set different pause windows per day?

Yes! Configure each weekday separately:

{
  "pauseWindows": {
    "monday": [
      {
        "startAt": { "hour": 12, "minute": 0 },
        "endAt": { "hour": 14, "minute": 0 }
      }
    ],
    "saturday": [
      {
        "startAt": { "hour": 0, "minute": 0 },
        "endAt": { "hour": 23, "minute": 59 }
      }
    ],
    "sunday": [
      {
        "startAt": { "hour": 0, "minute": 0 },
        "endAt": { "hour": 23, "minute": 59 }
      }
    ]
  }
}

Do pause windows apply to all timezones?

Pause windows use the program's timezone setting. If you're calling across multiple timezones, consider:

• Setting windows based on recipient timezones (segment by region)

• Using broader windows to cover multiple zones

What happens to a call during pause window?

• New contacts: Not pulled from the queue until pause ends

• In-progress calls: Complete normally

• Retries: Postponed until after the pause window

Can I add holidays as pause days?

Yes! Use advanced pause windows for specific dates:

{
  "pauseWindows": {
    "advanced": [
      {
        "startAt": "2025-12-25T00:00:00Z",
        "endAt": "2025-12-26T00:00:00Z"
      },
      {
        "startAt": "2025-01-01T00:00:00Z",
        "endAt": "2025-01-02T00:00:00Z"
      }
    ]
  }
}

---

Audio & Media

What audio formats are supported?

Upload audio files via POST /audio-management/upload using multipart/form-data. The system processes and converts files automatically.

Supported content types include:

• audio/wav

• audio/mp3

• audio/mpeg

Audio is processed to telephony-optimized format (8kHz sample rate, mono).

How do I upload audio files?

POST /audio-management/upload
Content-Type: multipart/form-data

file: [binary audio file]
title: "Welcome Message"
description: "Greeting for customers"
usageType: "welcome"
tags: ["greeting", "intro"]

Response includes the id to use in your Play nodes.

Can I use text-to-speech?

Yes! The Play node supports dynamic content types:

• audioFile: Pre-recorded audio

• number: Spoken numbers (e.g., account balance)

• date: Spoken dates

• word: Dictionary words

Configure language (ar or fr) and mode for each item.

What's a dictionary used for?

Dictionaries map keys to audio files for dynamic content. For example, a "Numbers" dictionary might have:

• Key "1" → audio of "one" spoken

• Key "100" → audio of "one hundred" spoken

• Key "thousand" → audio of "thousand" spoken

Use dictionaries in Play nodes to dynamically construct spoken content like amounts or dates.

How do I update an audio file?

To update metadata (title, description, tags):

PUT /audio-management/audio/:id
{
  "title": "Updated Welcome Message",
  "tags": ["welcome", "v2"]
}

To replace the audio content, upload a new file and update your flows to reference the new audio ID.

---

Reporting & Analytics

How do I see call results?

Use the Call Report API:

GET /call-report/:jobId

This returns:

• Job status (queued, active, completed, failed)

• All attempts with outcomes

• Flow execution path (which nodes ran)

• Event timeline (dial, answer, play, hangup, etc.)

What statuses can a call have?

Status	Description
completed	Call answered and flow completed successfully
no_answer	Recipient didn't answer (timeout)
busy	Line was busy
rejected	Recipient declined the call
voicemail	Answering machine detected
failed	System error during call
cancelled	Call was cancelled
user_hangup	Recipient hung up during the call

Can I export call reports?

Yes, the API returns JSON data that you can process and export. Query individual reports with GET /call-report/:jobId or build custom exports using the data.

How long is call data retained?

Call report data is persisted in the database and available even after background jobs are cleaned up. Retention periods depend on your organization's plan and settings.

Can I see which flow node caused a failure?

Yes! The call report includes flowExecution.executionPath:

{
  "executionPath": [
    {
      "nodeId": "dial-1",
      "nodeType": "dial",
      "outputPath": "onAnswer",
      "timestamp": "2025-12-16T11:15:00.071Z"
    },
    {
      "nodeId": "play-welcome",
      "nodeType": "play",
      "outputPath": "onError", // Error occurred here
      "timestamp": "2025-12-16T11:15:05.000Z"
    }
  ]
}

The outputPath shows which branch was taken, including error paths.

---

Troubleshooting

I'm getting 401 Unauthorized

Causes:

• API key expired or revoked

• Missing or malformed Authorization header

• Typo in your API key

Solutions:

1. Check header format: Authorization: Bearer YOUR_API_KEY

2. Verify you're using the correct API key

3. Contact our team if you need a new API key

I'm getting 429 Too Many Requests

You've hit the rate limit. Solutions:

1. Reduce request frequency - Add delays between calls

2. Implement exponential backoff - Wait longer after each retry

3. Batch operations - Use bulk endpoints like /contact/upsert

4. Check response headers for rate limit details

Calls show "error" but no details

Check the call report for more information:

GET /call-report/:jobId

Look at:

• outcomeReason for error description

• flowExecution.executionPath for which node failed

• events array for detailed timeline

Common causes: invalid audio file, misconfigured flow, missing node outputs.

My program won't start

Verify:

1. startAt is in the future - Or already passed if you want immediate start

2. Audience is not empty - AudienceEmptyError if no contacts

3. No existing running execution - ExecutionAlreadyRunningError

4. Program status is active - Not draft or archived

Launch with: POST /programs/:id/launch

Contacts aren't receiving calls

Check:

1. Phone format - Must be 3-20 characters, preferably E.164

2. Audience membership - Contact must be in the program's audience

3. Pause windows - Calls might be paused

4. Execution status - Must be running, not paused or stopped

5. DID pool - Program must have valid caller IDs

Flow execution stops unexpectedly

Common causes:

1. Missing output connections - Node has no path for the outcome that occurred

2. No default fallback - Add default outputs as safety nets

3. Invalid variable reference - Trying to read undefined variable

4. Audio file not found - Invalid audioId in Play node

Use POST /flows/validate to catch issues before launching.

---

Best Practices

How many contacts can I call at once?

This depends on:

• Your organization's concurrency limits

• DID pool size (more numbers = more parallel calls)

• System capacity

Start with smaller audiences and scale up. Monitor execution progress with GET /program-executions/:id to see contactsInProgress.

What's the ideal call window?

General guidelines:

• Business hours: 9 AM - 6 PM local time

• Avoid: Early morning, late evening, meal times

• Best days: Tuesday - Thursday typically have highest answer rates

Use pause windows to block unsuitable times:

{
  "pauseWindows": {
    "monday": [
      {
        "startAt": { "hour": 0, "minute": 0 },
        "endAt": { "hour": 9, "minute": 0 }
      },
      {
        "startAt": { "hour": 18, "minute": 0 },
        "endAt": { "hour": 23, "minute": 59 }
      }
    ]
  }
}

How do I avoid being marked as spam?

1. Use verified caller IDs - Legitimate DIDs with proper registration

2. Respect do-not-call lists - Remove contacts who opt out

3. Limit call frequency - Don't call the same person repeatedly in short periods

4. Call during appropriate hours - Use pause windows

5. Provide opt-out - Include a DTMF option to stop receiving calls

6. Identify yourself - Play a clear greeting identifying your organization

Should I use API keys or JWT in production?

Use API keys for:

• Server-to-server communication

• Background jobs and automation

• CI/CD pipelines

• Scheduled tasks

Use JWT tokens for:

• User-facing applications

• Dashboard/admin interfaces

• Mobile apps

• Any context where a user is logged in

API keys are simpler for automation since they don't require refresh logic.

---

Still have questions?

If you couldn't find the answer you're looking for:

• Check our Troubleshooting Guide

• Browse the Core Concepts documentation

• Contact our support team