Autodialer

The autodialer runs outbound campaigns: a list of numbers that one extension calls one after the other, with a pause between calls, a ring timeout and retries for the numbers that did not answer. The calls themselves are placed by the NUACOM portal in the agent's browser; the API holds what the dialer works from — the campaigns and their settings, the numbers with their status and retry counters, and the statistics. Numbers can be loaded from your own lists or picked from Contacts.

Workflow (what the portal does)#

1. Campaigns: GET /v2/auto-dialer/campaigns lists them 15 per page (page), newest first, with an optional status filter. Account admins see every campaign; other users only those whose sign_to is their own extension. Each campaign carries numbers_count and a stats block.
2. Create: POST /v2/auto-dialer/campaigns with name (up to 250 characters), phone_number (the caller ID, one of the account's own numbers), delay (seconds between calls, at least 1), max_response_time (seconds to let a call ring before hanging up, at least 1), max_retries (how many more times a number that did not answer is tried, 0 or more), sign_to (the extension number that runs the campaign, e.g. "32"), optional time_to_recall (the wait before such a number may be dialled again, at least 1), optional status (defaults to initial) and optional contacts (up to 2000 numbers to load at once). Answers 201 with the campaign.
3. Load numbers: POST /v2/auto-dialer/campaign/{campaignId}/numbers/upload with {"numbers": ["+353861234567", "0861234568"]}, 1 to 2000 per request; the portal builds this list from a pasted text or a .txt file with one number per line. Numbers are validated for the account's country, normalised to international format, de-duplicated and skipped when already in the campaign; new ones start as initial. 204. To add one number, POST /v2/auto-dialer/campaign/{campaignId}/numbers with number or contact_id (the contact's mobile number, or its first number when it has no mobile) and an optional status; 201 with the number.
4. Read: GET /v2/auto-dialer/campaigns/{campaignId} for one campaign, GET /v2/auto-dialer/campaign/{campaignId}/numbers for its numbers (1000 per page, newest first) and GET /v2/auto-dialer/campaign/{campaignId}/numbers/{numberId} for one of them.
5. Dial (portal only): the agent presses Play in the portal. The browser places the calls through the agent's extension, moves the campaign to in_progress with PUT /v2/auto-dialer/campaigns/{campaignId}, records the outcome of each attempt on the number with PUT /v2/auto-dialer/campaign/{campaignId}/numbers/{numberId} (status), and sets the campaign back to initial when it stops. The API does not start or stop dialling.
6. Statistics: GET /v2/auto-dialer/campaigns/{campaignId}/stats answers {"answered": 10, "not_answered": 10, "all": 20, "percentage": 50}: the counts of numbers in those statuses, the total, and the integer share of numbers that are finished (answered or voicemail; a not_answered number is not finished because it may be retried). The same block is embedded in every campaign as stats.
7. Across campaigns: GET /v2/auto-dialer/calls lists the numbers of all the account's campaigns, filtered by campaign_id, agent (the campaign's sign_to), status, date_from and date_to (Y-m-d or Y-m-d H:i:s; a bare date covers the whole day), paginated with per_page (1–1000, default 50).
8. Edit and delete: PUT …/campaigns/{campaignId} takes any subset of the fields of step 2, plus contacts to load more numbers, and answers 202 with the campaign; PUT …/numbers/{numberId} takes number and status and answers 202. DELETE /v2/auto-dialer/campaigns/{campaignId} and DELETE /v2/auto-dialer/campaign/{campaignId}/numbers/{numberId} answer 204.

curl -X POST 'https://api.api-nuacom.com/v2/auto-dialer/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "October renewals",
    "phone_number": "+35312345678",
    "delay": 15,
    "max_response_time": 30,
    "max_retries": 2,
    "time_to_recall": 60,
    "sign_to": "32",
    "contacts": ["+353861234567", "+353871234568"]
  }'

Vocabulary#

A campaign's status is free text up to 50 characters; the portal uses initial (idle) and in_progress (dialling).

A number's status is one of:

Status	Meaning	Finished
initial	Not dialled yet.	no
in_progress	Being dialled now.	no
not_answered	Did not answer; eligible for a retry.	no
answered	Answered and completed.	yes
voicemail	Reached voicemail.	yes

Each number also carries retries (attempts made so far) and last_retry (when the last attempt was made). The portal's dialer reads them against the campaign settings: a number that did not answer is dialled again while retries is below max_retries, and only once time_to_recall has passed since last_retry.

Dial status lifecycle#

stateDiagram-v2
    [*] --> initial: loaded via upload, numbers.store or contacts
    initial --> in_progress: dialled
    in_progress --> not_answered: no answer
    in_progress --> answered: answered and completed
    in_progress --> voicemail: reached voicemail
    not_answered --> in_progress: retries < max_retries and time_to_recall elapsed
    answered --> [*]
    voicemail --> [*]

Roles and access#

• Every endpoint is open to any authenticated user of the account; there is no admin-only operation.
• Only the campaign list is filtered by role: non-admins get the campaigns assigned to their extension (none at all when their user has no extension). Every other endpoint checks only that the campaign belongs to the account, so a non-admin who knows a campaign id can read and change it.
• A campaign or number of another account, or an unknown id, answers 404 {"message": "Resource not found!"}.

Pitfalls#

• Two path shapes: campaigns live under /v2/auto-dialer/campaigns/{campaignId}, numbers under /v2/auto-dialer/campaign/{campaignId}/numbers (singular campaign).
• sign_to is the bare extension number ("32"), whatever the example in the reference suggests; any other value answers 422 The selected extension does not belong to your account.. A non-admin whose extension is not the campaign's sign_to does not see it in the list.
• phone_number must be one of the account's numbers, in any national or international spelling; it is stored as sent.
• Adding one number with number stores the string as sent: no format check beyond 30 characters, no normalisation and no duplicate check, unlike upload and contacts. Prefer upload, or contact_id, which resolves and normalises the contact's number. Sending neither answers 422 A number or contact_id is required; a contact without a phone number answers 422; a contact of another account 404.
• retries and last_retry are maintained by the dialer: the API reports them but does not accept them as input — PUT …/numbers/{numberId} takes number and status only.
• Successful updates answer 202, not 200.
• date_from and date_to on /v2/auto-dialer/calls filter by the date the number was added to its campaign, not by last_retry.
• Lists are paginated resources (data, links, meta); a single campaign or number is returned bare, without a data wrapper.
• Timestamps are ISO 8601 in UTC (2022-11-24T11:15:54.000000Z). With the account's ISO dates option, created_at and updated_at follow the requested timezone while last_retry stays in UTC.