What this API Does

It allows creating automated call campaigns (massive) in two modes:

• STANDARD: prerecorded audio (referenced by audioId)
• CUSTOM: text-to-speech (TTS) per contact (content), using a voice (voice = "Juan" or "Maria")

---

Authentication

All requests must include:

• x-auth: API key provided by Saem.

Unlike the SMS API, here prefix is a body field for campaigns, not a header in the CallB sending endpoints according to the guide.

---

Key Payload Concepts

Fields used in this API:

• subService: "standard" or "custom"

• prefix: origin country code (example: 57)

• gmt: local timezone in format +/-HH:MM (affects execution window)

• nameCampaign: campaign name

• mailbox: true/false (leave voicemail if the call is not answered)

• configProgramming: list of execution schedules

  • maximum 5 configurations

  • if more than one configuration is sent, a separate campaign is created for each

  • includes:

    • dateStart, dateEnd
    • reviews (retries)
    • configReview: retry conditions (max 5 retries)

• numbers:

  • STANDARD: list of phone numbers (without symbols)
  • CUSTOM: array of objects { number, content }

Retry Conditions (configReview)

Allowed values:

buzon, colgo, congestion, fallo, maquina, mcolgo, msatisfactorio, nocontesta, satisfactorio.

---

Load Limits

For JSON services:

• Maximum 200,000 records
• If exceeded → error CALLB_022

For Parquet:

• Maximum 500,000 records
• If exceeded → CALLB_022

---

STANDARD Flow: How to Build a Campaign

Step A: Obtain or Create audioId

The audioId field can be obtained:

• From the “Resources” module in the web platform (each audio has an ID), or
• By generating it via API (next step).

---

Step B: Generate Audio via API (optional but recommended)

If you automate campaign creation.

URL: https://apicallb.saem.tel/audio/generate Method: POST Headers: x-auth

Body fields:

• text
• voice
• resource_name (base name of the .wav file)

---

Step C: Create STANDARD Campaign (JSON)

URL: https://apicallb.saem.tel/send/massive Method: POST Headers: x-auth

Example Body

{
  subService: "standard",
  prefix,
  gmt,
  nameCampaign,
  audioId,
  configProgramming: [...],
  numbers: [...]
}

(numbers is a list of phone numbers)

---

CUSTOM Flow: TTS Campaign (Text-to-Speech)

Create CUSTOM Campaign (JSON)

URL: https://apicallb.saem.tel/send/massive Method: POST Headers: x-auth

Example Body

{
  subService: "custom",
  voice: "Juan" | "Maria",
  numbers: [{ number, content }, ...],
  prefix,
  gmt,
  configProgramming
}

---

Templates (CUSTOM)

Tags interpreted by the system per contact:

• {I} identifier
• {N} name
• {S} balance/value
• {T} phone number
• {E} email
• {C} account

---

Campaigns with Parquet

URL: https://apicallb.saem.tel/send/massive/parquet Method: POST Headers: x-auth Body: form-data (Parquet file + parameters)

File Rules

• STANDARD → Parquet file with column number
• CUSTOM → Parquet file with columns number and content

configProgramming must be sent in form-data as a JSON string, not as an object:

[{"dateStart":"...","dateEnd":"...","reviews":2}]

---

Campaign Creation Response

When a campaign is created, a summary response is returned containing:

• sends: count grouped by operator (includes "null" for invalid numbers detected)

• summary:

  • total_records
  • total_credits
  • seconds_aprox (approximate total seconds)

---

Errors

Authentication Errors

Code	HTTP Status	Description
AUTH.TOKEN_MISSING	400	x-auth header was not sent
API_KEY_NOT_FOUND	400	API key does not exist or is invalid
USER_NOT_FOUND	404	User associated with the API key not found
USER_INACTIVE	401	User is inactive and cannot run campaigns

---

Configuration Errors

Code	HTTP Status	Description
CALLB_015	404	Multimedia resource not found (audioId invalid)
CALLB_016	404	No configuration exists for the country/prefix
CALLB_018	400	Configured schedule is outside the allowed country range

---

Processing Errors

Code	HTTP Status	Description
CALLB_019	400	Invalid or malformed Parquet file
CALLB_021	402	Insufficient credits to execute the campaign
CALLB_022	400	Maximum number of records exceeded

---

Audio Generation Errors

Code	HTTP Status	Description
CALLB_AUD_001	400	resource_name invalid or wrong format
CALLB_AUD_002	409	Audio resource already exists (duplicate name)