Triggering calls
To call one customer, send a POST request to the automation's trigger URL. Copy the URL from the
automation's Trigger and credentials tab in the console, which admins and engineers can see. It
has the form https://api.signals.pressone.africa/automations/{automation_id}/calls, where
the automation id starts with sig_. Both operations on this page are listed in the
Automations API reference.
Authentication
Authenticate with an organization API key sent as a Bearer token in the Authorization header. The
key must hold the service_configuration:write scope and cannot be restricted to a subaccount. The
request runs in the automation's own project, so it does not need an X-Project-ID header. A key
that has been revoked or has expired may continue to work for up to 60 seconds. See
Authentication to create a key.
The request
The body is a JSON object of at most 16 KiB.
| Field | Required | Description |
|---|---|---|
phone_number | Yes | The number to call, in E.164 format: a + followed by 8 to 15 digits, the first of which is not 0. |
name | No | The customer's name, used for the {{name}} variable. At most 120 characters. |
event_id | No | Your identifier for this trigger, used for idempotency. At most 120 characters and not blank. |
parameters | No | Values for the message's other variables, such as time. At most 40 keys. Each key starts with a letter and contains only letters, digits and underscores, up to 64 characters. Each value is a string of at most 500 characters, a number or a boolean. |
metadata | No | Any JSON object of at most 4096 bytes. Signals stores it with the run and returns it in every webhook event. |
Code
Code
Signals applies the suppression rules before it answers, then responds with the
run as it stands, using camelCase field names. id and runId carry the same run id and signalId
is the automation id. A run that passed the rules is queued with outcome and suppressionReason
still null; a run stopped by a rule already shows status finished, outcome suppressed and
the reason; a run that arrived outside calling hours on an automation set to wait shows
waiting_hours. A 202 Accepted therefore means Signals accepted the request, not that the call
has been placed. Follow the run through its webhook events or the
console.
Idempotency
Use event_id to make triggers safe to retry. Signals keeps one run per event_id for each
automation. If you send the same event_id again, Signals returns 200 OK with the original run as
it is now and does not call the customer a second time.
Derive the event_id from the business event rather than generating it at send time. For an
appointment reminder, appt-77120-2026-10-30 identifies one booking on one day, so every retry of
that reminder carries the same value. A new UUID per attempt defeats the purpose, because two ids
for the same event produce two calls. If you omit event_id, Signals generates one in the form
auto_<uuid>, and retrying such a request calls the customer again.
Responses and errors
Error responses use the problem format described in
Requests and errors. The code member identifies the
reason, and on a 422 response the field member names the invalid field.
| Status | code | Meaning | What to do |
|---|---|---|---|
202 | Signals created a new run. | No action is required. | |
200 | The event_id matches an earlier trigger, and the body is the original run. | No action is required. The customer is not called again. | |
401 | unauthenticated | The API key is missing or not recognised. | Check the Authorization header and the key. |
403 | api_key_scope_missing | The key does not hold service_configuration:write. | Use a key that has the scope. |
403 | api_key_subaccount | The key is restricted to a subaccount. | Use an organization API key. |
404 | automation_not_found | Your organization has no automation with this id. | Check the automation id in the trigger URL. |
413 | The body is larger than 16 KiB. | Reduce the size of the request body. | |
422 | invalid_phone_number, invalid_name, invalid_event_id, event_id_too_long, invalid_parameters, invalid_metadata, metadata_too_large, invalid_body | A field is invalid. invalid_body means the body was not a JSON object. | Correct the field named in field and send the request again. |
429 | rate_limited | The automation received more than 20 requests in one second. The response carries Retry-After: 1. | Wait one second, then retry with the same event_id. |
503 | try_again, identity_unavailable | Signals could not store the request or verify the key. A try_again response carries Retry-After: 1. | Retry with the same event_id. |
Retry 429 and 503 responses, and requests that time out, with the same event_id. Correct the
cause of a 401, 403 or 422 before you send the request again.
Suppression rules
Before dialling, Signals checks the automation's rules in the order below and stops at the first
one that applies. A run stopped by a rule finishes with outcome suppressed and
suppressionReason records the rule. A suppressed run is a deliberate decision not to call, not a
failed call. You can switch off the do-not-call, daily-limit and calling-hours rules in step 6 of
the builder.
| Rule | suppressionReason |
|---|---|
| The automation is switched off. | automation_off |
| The number is on the do-not-call list. | do_not_call |
| The automation has already called this number today, counted in the calling-hours time zone. | already_called_today |
The trigger arrives outside calling hours and the automation is set not to call outside them. If it is set to wait instead, the run takes the status waiting_hours and is called when calling hours open. | outside_hours |
Run status
| Field | Values |
|---|---|
status | staged, queued, waiting_hours, scheduled, dialing, placed, ringing, answered, finishing, finished |
outcome | null until the run finishes, then one of completed, no_answer, busy, suppressed, failed, rejected, expired, duplicate |
suppressionReason | null, or one of automation_off, do_not_call, already_called_today, outside_hours, no_longer_owed |
Cancel a run
If a call is no longer needed, for example because the customer rescheduled, cancel the run before
Signals dials it. Send a POST request to the trigger URL with /cancel appended, using the same
API key, and identify the run by the event_id you triggered it with. Unlike on a trigger,
event_id is required here.
Code
Code
If the run has not been dialled yet, Signals suppresses it and returns it with 200 OK. If it has
already been dialled or has finished, Signals returns the run unchanged with 200 OK and does not
end a call in progress. If no run of the automation has that event_id, the response is 404 with
code event_id_unknown. A missing or invalid event_id returns 422, and the authentication,
rate-limit and storage errors match those of a trigger.