External API and webhooks¶
Requires the "General settings" permission.
The External API page (menu CONFIGURATION) is used to connect Thelgo to other systems, for example your CRM or a contact form on your website. It has two tabs:
- API keys: the keys with which an external system can read and write data in Thelgo (contacts, campaigns, outcomes);
- Webhooks: the addresses to which Thelgo sends a notification when something happens (an outcome, an appointment, a new contact).
This page is also meant for whoever develops the integration: the technical sections are marked as such.
The API keys tab shows, at the top, the limit of requests per second, then How to use the public API (closed) and the box to create a key with its Name.
API keys¶
Creating a key¶
- Open the API keys tab.
- In the Name field write what the key is for (e.g. "CRM integration"): you will need it to recognize the key in the list and in the audit log.
- Press Create key.
- The message "Copy this key now: it will not be shown again." appears with the full key: press Copy and hand it over securely to whoever develops the integration.
The key is shown only once
Thelgo stores the key only in encrypted form: after you leave or reload the page it can no longer be viewed. If you lose it, create a new key and revoke the old one.
Create a different key for each external system: you will be able to revoke one without stopping the others, and in the audit log you will see which system did what.
The key list¶
For each key you see the name, the first letters of the key (to recognize it), the creation date and the last used date. Clicking the name opens the list of the last 50 requests received with that key (method, address, date and time, response code: green if successful, red if in error). It is the first place to look if an integration "does not work".
Revoking, reactivating and deleting¶
- The switch on the right revokes the key (the Revoked label appears): before proceeding the browser asks for confirmation with the message "Revoke the key "name"? Systems using it will stop working immediately.". After confirmation every request with that key is rejected. You can reactivate it with the same switch (reactivation does not ask for confirmation).
- Only a revoked key shows the Delete button, which deletes it permanently after a confirmation.
Creation, revocation, reactivation and deletion are recorded in the Audit log. If an operation fails, the reason appears at the bottom as a red message.
Revoke a compromised key right away
After confirmation the switch acts immediately. If a key has fallen into the wrong hands or the integration provider has changed, revoke it and create a new one.
Request limit¶
At the top of the tab you find "Limit: … requests per second": it is the maximum number of requests per second the account can receive with API keys, set by the service provider. Beyond the limit the external system gets a 429 error response and must retry shortly after.
What the public APIs allow¶
The How to use the public API box summarizes the endpoints; API documentation (Swagger) opens the full, interactive documentation, to hand over to whoever develops the integration.
With a key the external system can:
| Area | Operations |
|---|---|
| Contacts | Create a contact and link it to a campaign; read it; update its personal data, phone numbers and dynamic fields |
| Campaigns | List the account's campaigns, with the outcome profile assigned to each one (read only) |
| Outcome profiles | List the outcome profiles with the details of each outcome and their identifiers (read only) |
| Outcomes | Record the outcome of a contact, also with its details; read the current outcome and the history; edit notes and callback date of the last outcome; delete the last outcome |
Things to know, also for you as administrator:
- Operations done via API appear in Thelgo as performed by the system user API Pubbliche, which in the reports and in the Audit log appears as "API Pubbliche (sistema)" (Public APIs (system)), and in the audit log they carry the name of the key used. If you want an outcome to be attributed to a specific operator, indicate it with the optional
operatoreIdfield (see below). - An outcome entered via API follows the same rules as the operator interface ("Creation follows the same validation rules as the operator interface (e.g. a callback date is required for the "Call back" outcome)."): it counts for automatic callbacks, the Not authorized block and the reports, exactly like an outcome given by an operator. In campaigns where Positive requires a mandatory appointment, a Positive via API is rejected because the APIs do not book appointments. The same applies to campaigns with Survey required for positive outcome (see Surveys): the APIs do not fill in surveys and the Positive is refused with "For the Positive outcome you must first complete the survey."
- "Updates are limited to notes and the callback date": to change the result of a contact the external system must record a new outcome.
- Deleting an outcome via API brings the contact's current outcome back to the previous one, but does not recalculate the attempt counters or the date of the next callback.
- A contact created via API must have at least one phone number; dynamic fields are indicated by their name as defined in the database schema (see Dynamic fields).
Technical details for the developer¶
Authentication: every request must contain the header
Authorization: Bearer thelgo_live_...
"Header on every request. No login, no session cookie." A revoked or wrong key gets 401.
Base URL: https://<your account's domain>/api/public/v1 (the exact address is shown on the page).
| Method | Path | Description |
|---|---|---|
POST |
/nominativi |
Creates a contact and links it to a campaign (campagnaId required, up to 9 telefoni, campiDinamici by name) |
GET |
/nominativi/{id} |
Reads a contact |
PUT |
/nominativi/{id} |
Updates a contact's personal data |
GET |
/campagne |
Lists the account's campaigns (id, name, type, status, dates, number of contacts, profiloEsitiId) |
GET |
/profili-esiti |
Lists the outcome profiles with the details of each outcome (see below) |
POST |
/esiti |
Records the outcome of a contact (nominativoId, campagnaId, esitoCodice, optional dettaglioEsito1Id and dettaglioEsito2Id, note, dataRichiamo, richiamataPubblica, optional dataOraChiamata, optional operatoreId) |
GET |
/esiti?nominativoId=&campagnaId= |
Current outcome and history of the previous outcomes of a contact in a campaign |
PUT |
/esiti |
Updates notes/callback date of the most recent outcome (nominativoId, campagnaId, note, dataRichiamo) |
DELETE |
/esiti?nominativoId=&campagnaId= |
Deletes the most recent outcome of a contact in a campaign |
Outcome operator (operatoreId, optional): by default the outcome created via API is attributed to the system user API Pubbliche (in the reports "API Pubbliche (sistema)"). If the external system knows which operator actually handled the contact, it can indicate their identifier in operatoreId: the outcome (and the audit log row) is then attributed to that operator. The operator must be enabled on the campaign given; otherwise the request is rejected with "The given operator is not enabled for this campaign.".
Avoid indicating an operator who is working
Recording an outcome on behalf of an operator uses the same save as the operator interface: if that operator currently has a call in progress started from Thelgo, the call may be closed. Indicate an operatoreId only for outcomes about contacts that are already concluded.
Outcome details (outcome profiles): if a campaign uses an outcome profile, the outcome can carry a first-level detail and possibly a second-level one.
GET /campagnereturns for each campaign theprofiloEsitiIdfield, which isnullif the campaign has no profile.GET /profili-esitilists the profiles: for each oneid,nomeandesiti, with one element for each outcome that has details (esitoCodice,dettaglio1Obbligatorio,dettagli). Each element ofdettaglihasid,descrizione,dettaglio2Obbligatorioanddettagli2(list ofidanddescrizione). Only active profiles and details are included.- In
POST /esitiindicatedettaglioEsito1Idand, if needed,dettaglioEsito2Idwith theidvalues taken from that list. They are always optional via API, even if they are required for the operator in the profile. If you indicate them they must belong to the campaign's profile and to the outcome: the second requires the first and must be one of its second details. POST /esitiandGET /esitireturndettaglioEsito1Id,dettaglioEsito1,dettaglioEsito2IdanddettaglioEsito2(id and description), empty if not chosen.
If the details are not valid the request gets 400 with a message: "The campaign has no outcome profile: you cannot set outcome details.", "The outcome profile of the campaign has no details for outcome "…".", "A second-level detail also needs a first-level detail.", "Detail … is not valid for outcome "…" in the outcome profile of the campaign (it does not exist, is disabled or belongs to another outcome)." or "Second-level detail … does not belong to detail "…" (it does not exist or is disabled).".
Outcome codes accepted in esitoCodice:
| Code | Outcome |
|---|---|
POSITIVO |
Positive |
NEGATIVO |
Negative |
OCCUPATO_NON_RISPONDE |
Busy / No answer |
RICHIAMARE |
Call back (requires dataRichiamo) |
NON_AUTORIZZA |
Not authorized |
DINAMICO_1, DINAMICO_2, DINAMICO_3 |
Custom outcomes, if active (see General settings) |
Idempotency: "On creation (POST) requests you can send the "Idempotency-Key" header with a unique value: if the same request is resent with the same key (e.g. after a timeout), you get back the already-produced response instead of a duplicate." The response is remembered for 24 hours and only if the original request succeeded.
Errors: on an error (400, 404, 429…) the response has the body { "code": "...", "message": "...", "params": { ... } }. code is a stable code on which to base the external system's code, message an explanation in English and params the values quoted in the message. Do not rely on the text of message: it may be improved over time. 400 means a validation problem, 404 that the contact or campaign does not exist, 429 that the request limit was exceeded.
Webhooks¶
A webhook is a web address of your external system to which Thelgo automatically sends a notification when an event happens. This way the CRM, for example, is updated in real time without having to query Thelgo continuously.
The Webhooks tab has the creation form with the Target URL field and the Events to tick (three, see below), and the Create webhook button. The configured webhooks appear below.
Available events¶
| Event | Code | When it is sent |
|---|---|---|
| Outcome assigned to a contact | esito.assegnato |
When an operator (also in a Predictive campaign) or an API call records an outcome, including Quality Check outcomes |
| New appointment scheduled | appuntamento.fissato |
When a new appointment is booked |
| New contact created | nominativo.creato |
When a new contact is created (manual entry by an administrator or operator, via API or through an import) |
Imports
The contacts loaded with an import each generate a nominativo.creato event, all sent at the end of the import: for a large file your system will receive many events in a short time. campagnaIds contains the campaigns the contact was added to during the import (it is empty if it was not added to any). Adding contacts that already exist to a campaign with Add contacts does not generate the event.
Creating a webhook¶
- Open the Webhooks tab.
- In Target URL write the address provided by whoever develops the integration (it must start with
https://orhttp://; always usehttps://). - In Events tick at least one event.
- Press Create webhook.
- "Copy this secret now: it will not be shown again. Use it to verify the signature of incoming requests." appears: press Copy and hand it to the developer together with the URL.
To receive different events at different addresses, create more webhooks.
Checking deliveries¶
Click a webhook's URL to see the last 50 deliveries: event, date and time, Delivered or Failed with the number of attempts and the last error (e.g. "HTTP 500"). If an external system says it receives nothing, look here.
Revoking and deleting¶
It works as for keys: the switch revokes (or reactivates) the webhook; to revoke it the browser asks for confirmation with the message "Revoke the webhook to "url"?", reactivation does not ask. A revoked webhook shows Delete to delete it permanently. While it is revoked Thelgo sends nothing, not even the attempts still pending.
Technical details for the developer¶
The Webhook documentation button opens a dedicated page, with an example payload for each event, which you can share with whoever develops the integration.
Format: each event arrives as a POST request to the configured URL, with a JSON body and these headers:
POST <configured url>
Content-Type: application/json
X-Thelgo-Event: esito.assegnato
X-Thelgo-Signature: a3f1c9...
Signature verification: compute the HMAC-SHA256 of the request body (the raw string received, not re-serialized) using the secret shown at creation, and compare the result, in lowercase hexadecimal, with the X-Thelgo-Signature header. If they do not match, discard the request: it does not come from Thelgo.
Confirmation and retries: the external system must respond with a 2xx code within 15 seconds. On error or timeout Thelgo automatically retries up to 8 times, with an increasing interval between attempts.
Event content (dates in UTC):
esito.assegnato
{
"nominativoId": 1234,
"campagnaId": 56,
"livello": "PrimoLivello",
"esitoCodice": "RICHIAMARE",
"dettaglioEsito1Id": 7,
"dettaglioEsito1": "Cliente impegnato",
"dettaglioEsito2Id": null,
"dettaglioEsito2": null,
"note": "Richiamare dopo le 15",
"dataRichiamo": "2026-10-14T13:00:00Z",
"dataOraChiamata": "2026-10-13T09:12:30Z"
}
dettaglioEsito… fields are filled in only if the outcome has details chosen (campaign with an outcome profile), otherwise they are null.
livello is PrimoLivello for normal outcomes and QualityCheck for those of the Quality Check (codes QC_CONFERMATO, QC_ANNULLATO, QC_RICHIAMARE, QC_OCCUPATO_NON_RISPONDE).
appuntamento.fissato
{
"appuntamentoId": 789,
"nominativoId": 1234,
"campagnaId": 56,
"agenteId": 12,
"dataOraAppuntamentoInizio": "2026-10-20T10:00:00Z",
"dataOraAppuntamentoFine": "2026-10-20T10:30:00Z"
}
nominativo.creato
{
"nominativoId": 1234,
"campagnaIds": [56]
}