Skip to content

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

  1. Open the API keys tab.
  2. 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.
  3. Press Create key.
  4. 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 operatoreId field (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 /campagne returns for each campaign the profiloEsitiId field, which is null if the campaign has no profile.
  • GET /profili-esiti lists the profiles: for each one id, nome and esiti, with one element for each outcome that has details (esitoCodice, dettaglio1Obbligatorio, dettagli). Each element of dettagli has id, descrizione, dettaglio2Obbligatorio and dettagli2 (list of id and descrizione). Only active profiles and details are included.
  • In POST /esiti indicate dettaglioEsito1Id and, if needed, dettaglioEsito2Id with the id values 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 /esiti and GET /esiti return dettaglioEsito1Id, dettaglioEsito1, dettaglioEsito2Id and dettaglioEsito2 (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

  1. Open the Webhooks tab.
  2. In Target URL write the address provided by whoever develops the integration (it must start with https:// or http://; always use https://).
  3. In Events tick at least one event.
  4. Press Create webhook.
  5. "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"
}
The 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]
}