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)

What it Does

The SMS API allows sending SMS messages in two ways:

• Single (one number per request).

• Bulk (many numbers in one request) using:

  • JSON (up to 200,000 records).
  • Parquet (up to 500,000 records and recommended for performance).

---

Authentication and Required Headers

All requests must include:

• x-auth: API key provided by Saem Colombia (if missing, the request will be rejected).
• x-prefix: country code sent as a header (example: 57).

Rule: without these headers, the API will not process the request.

---

Data Model (Input Parameters)

The guide lists the following fields (depending on endpoint/format):

• from: authorized sender identifier.

• flash: required in all services; values yes or no.

• numbers: list of messages to send; each item includes:

  • to: destination number.
  • content: message text (must include the required shortname, see errors section).

• msg_id (optional): unique message ID; if not provided, the system will generate it.

Important note: the guide specifies “content including the shortname”, and the error SHORTNAME_NOT_FOUND occurs if it is missing.

---

Endpoint: Single Message Sending

URL: https://apisms.saem.tel/v3/send

Method: GET

Headers: x-auth, x-prefix

How it Works

• Parameters are sent as query params (to, content, from, flash).
• The system processes one SMS to a single recipient.

When to Use

• Individual notifications (OTP, confirmations, alerts, etc.).

---

Endpoint: Bulk Sending in JSON

URL: https://apisms.saem.tel/v3/send

Method: POST

Headers: x-auth, x-prefix

Body: JSON

Limit

• Maximum 200,000 records per JSON request.
• If exceeded → error SMS_008.

How it Works

• You send an object with metadata (e.g., from, flash) and the numbers list.
• Each element inside numbers represents an SMS to be sent.

Practical Recommendation

• If you need traceability, send your own msg_id (UUID) to correlate messages.
• If not provided, the API will generate it automatically.

---

Endpoint: Bulk Sending in Parquet

URL: https://apisms.saem.tel/v3/send/parquet

Method: POST

Headers: x-auth, x-prefix

Body: form-data (Parquet .parquet file + additional parameters)

Limit

• Maximum 500,000 records.
• If exceeded → error SMS_008.

How it Works

• Instead of sending numbers in JSON, you upload a Parquet file containing the records.

The guide recommends Parquet because it provides:

• faster uploads,
• smaller file size,
• better overall performance.

---

Output Parameters

Fields returned in the response (especially for bulk campaigns):

• request_id: unique ID of the bulk campaign.
• total_credits: credits consumed.
• records: total number of messages processed.
• total_pdu_count: total PDUs generated across all messages (useful to understand segmentation of long SMS messages).

---

Error Handling

Authentication Errors

Code	HTTP Status	Description
AUTH.TOKEN_MISSING	400	The x-auth header was not sent.
API_KEY_NOT_FOUND	400	The provided API key does not exist or is invalid.
USER_NOT_FOUND	404	The user associated with the API key was not found.
USER_INACTIVE	401	The user is inactive.
COUNTRY_001	400	The prefix (x-prefix) is not associated with any country or is not configured.

---

Sending / Validation Errors

Code	HTTP Status	Description
SMS_002	402	Insufficient credits (prepaid accounts).
SMS_008	400	The maximum allowed number of records was exceeded.
SMS_009	400	Invalid or malformed Parquet file.
DUPLICATED_MSG_ID	400	The msg_id has already been used in a previous campaign.
FORBIDDEN_TERMS	400	The message content contains prohibited terms.
SHORTNAME_INACTIVE	400	The shortname is inactive.
SHORTNAME_NOT_FOUND	400	The shortname was not found in the message content.
CONTENT_TOO_LONG	400	The message content exceeds the allowed length.