Lokalt REST-API
AI Softphone har et REST-API for CTI-integrasjon: et program på samme maskin kan ringe og styre samtaler, lese kontakter, samtalehistorikk og SIP-kontoer, og følge med på samtalene som pågår. Ingen SDK, ingen mellomledd i skyen og ingen lytter som er eksponert mot nettverket. Forespørsler og svar er JSON, så curl eller en hvilken som helst HTTP-klient er nok.
API-et er av etter installasjonen; ingenting lytter før du slår det på. Etter det lytter det bare på loopback-grensesnittet — et lite nettgrensesnitt som bare svarer denne maskinen — og kan ikke nås fra kontornettverket, et VPN eller en annen maskin.
Bruk API-et når programmet ditt trenger data fra telefonen eller må styre en samtale. Bruk webhooker når det må reagere på samtaler mens de skjer, uten å spørre om og om igjen. De fleste integrasjoner bruker begge; de er uavhengige av hverandre.
Slå det på
Åpne Innstillinger → Integrasjon, og gå til Lokal styring.
- Slå på La andre programmer på denne maskinen styre telefonen. Serveren starter med én gang.
- Behold standard Port,
8377, med mindre et annet program allerede bruker den. - Sett eventuelt en Nøkkel. Når den er lagret, viser feltet Lagret — skriv for å erstatte det.
- Velg under Tilgang gruppene som skal åpnes: Kontakter, Samtalehistorikk, Samtaler, og styringen av dem, Kontoer, Innstillinger, Tellere (målingene). En gruppe som er av, filtreres ikke, men tilbys ikke i det hele tatt.
- Prøv det:
curl http://127.0.0.1:8377/accounts. Er svaret JSON, virker API-et.
Ingen egen tjeneste installeres, og det trengs ingen omstart. Den delen av programmet som gjør dette, kan slås av under Moduler (Integrasjon).
API-ets egen side
Åpne API-ets egen side åpner http://127.0.0.1:8377 i en nettleser. Adressen svarer med en liste over alt den tilbyr, på engelsk; adressene som leser noe, er lenker du kan følge.
Tilgang og nøkkelen
Hva et program får gjøre, avhenger av om det endrer lagrede data, ikke av om det leser:
- Uten nøkkel kan ethvert program på maskinen lese alt i gruppene som er åpnet, og styre samtaler: ringe, svare, legge på, sette på vent, gjenoppta, sette over og sende DTMF.
- Med nøkkelen i hodet
Authorizationkan det også bruke endepunktene som endrer det som er lagret. Uten nøkkelen vises ikke disse endepunktene på API-ets egen side, og de svarer401. Er det ikke satt noen nøkkel i det hele tatt, kan ingenting endre det som er lagret.
Nøkkelen lagres i maskinens nøkkelring, ikke i innstillingsfilen, og returneres aldri av /settings.
Uten nøkkel kan ethvert program som kjører på denne maskinen, styre telefonen, også svare på samtaler. På en personlig arbeidsstasjon er det som regel greit. På en delt eller administrert maskin bør du sette en nøkkel og behandle den som et hvilket som helst annet passord. Nøkkelen beskytter bare forespørslene som endrer lagrede data, ikke samtalene: vil du holde andre programmer unna samtalene, slår du av Samtaler, og styringen av dem under Tilgang.
Endepunkter
Grunnadressen er http://127.0.0.1:8377. Endepunktene nedenfor trenger ingen nøkkel.
| Metode | Sti | Gjør |
|---|---|---|
| GET | /metrics | Tellerne, i Prometheus-format. |
| GET | /ui | Listen over opptak, som en HTML-side. |
| GET | /ui/recordings/{id} | Et opptak med utskriften, som en HTML-side. |
| GET | /ui/recordings/{id}/audio | Lyden til siden over. |
| GET | /contacts | Kontaktene. |
| GET | /contacts/{id} | Én enkelt kontakt. |
| GET | /history | Samtalehistorikken, nyeste først. Godtar ?limit=, ?missed=true og ?declined=true. |
| GET | /calls | Samtalene som pågår. |
| POST | /calls | Ringer en samtale: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Svarer på en samtale. |
| POST | /calls/{id}/hangup | Legger på en samtale. |
| POST | /calls/{id}/hold | Setter en samtale på vent. |
| POST | /calls/{id}/resume | Tar den av vent. |
| POST | /calls/{id}/dtmf | Sender toner: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Setter over samtalen: {"target": "..."}. |
| GET | /accounts | SIP-kontoene og registreringstilstanden deres. Aldri et passord. |
| GET | /settings | Hele konfigurasjonen, uten hemmelighetene. |
| GET | /taxonomy | Kategorier, etiketter og signaler, med kodene deres. |
Endepunkter som krever nøkkelen
De endrer det som er lagret, så hver forespørsel må ha med nøkkelen i hodet Authorization. API-ets egen side viser dem bare til en forespørsel som har den med.
| Metode | Sti | Gjør |
|---|---|---|
| POST | /contacts | Legger til en kontakt: {"name": "...", "number": "...", "account_id": "..."}; account_id er valgfri. |
| PUT | /contacts/{id} | Erstatter en kontakt. |
| DELETE | /contacts/{id} | Fjerner en kontakt. |
| DELETE | /history/{id} | Glemmer én samtale i samtaleloggen. |
| DELETE | /history | Glemmer hele samtaleloggen. Det kan ikke angres. |
| PUT | /accounts/{id} | Erstatter innstillingene for en konto. Passordet er ikke blant dem. |
| PUT | /settings | Erstatter innstillingene. |
Hver identifikator er en UUID utstedt av telefonen: en samtales id kommer fra /calls eller fra svaret på POST /calls, en kontos id fra /accounts.
Feltnavn er i snake_case, og endelsen forteller typen: _id er en referanse til en UUID, _ts er et tidspunkt i Unix-millisekunder (UTC), _s er en varighet i sekunder. Det samme gjelder for webhooker; bare /settings har egne navn. I REST-API-et er disse verdiene JSON-tall, og et ukjent tidspunkt er null.
Eksempel: ringe en samtale
POST /calls ringer en utgående samtale. Innholdet er JSON med number som skal ringes, og eventuelt account_id for kontoen det skal ringes fra:
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
Svaret er identifikatoren for den nye samtalen:
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
numberer påkrevd. Uten det er svaret400 {"error":"a call needs a number"}, og ingenting ringes.- Nummeret fullføres på den valgte kontoen slik nummerfeltet fullfører det:
1020sendes somsip:1020@pbx.example.com.POST /calls/{id}/transferfullfører sitttargetpå samme måte; et mål som allerede har et skjema eller en@, sendes som det er. account_ider valgfritt; ta det fraGET /accounts. Uten det går samtalen ut på kontoen som er valgt i hovedvinduet.- Bruk
idi/calls/{id}/…:hangup,hold,resume,dtmfogtransfer. Webhookene for denne samtalen har sammeid.
Fra en nettside: klikk for å ringe
En side som kaller 127.0.0.1, når maskinen nettleseren kjører på — den samme telefonen kjører på —, så en klikk-for-å-ringe-knapp i et CRM trenger ingen egen server:
async function dial(number) {
const r = await fetch("http://127.0.0.1:8377/calls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ number }),
});
if (!r.ok) console.warn("softphone:", (await r.json()).error);
}
Hva svarene inneholder
Samtaler som pågår: GET /calls
Hver samtale har sin id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts og callstate_ts.
stateerdialing,ringing-out,ringing-in,active,hold(satt på vent av denne telefonen),onhold(satt på vent av den andre parten),conferenceellerended. Når flere gjelder, vinnerconferenceoverhold, ogholdoveronhold.mutedsier om mikrofonen er slått av i samtalen; å slå av lyden endrer ikkestate.seance_ider samtalen i videre forstand: samtaler som er knyttet sammen ved en overføring, en konsultasjon eller en konferanse, deler den.event_tser når svaret ble laget. Sammenlign den medcallstate_tsfor å se hvor lenge samtalen har vært i tilstanden, uten å stole på din egen klokke.
Kontoer: GET /accounts
Hver konto har sin id (account_id alle andre steder), innstillingene — transport (udp, tcp eller tls), port, registrar, outbound_proxy, expiry_s og andre —, om den er enabled, og sin state på sentralen: registered mens linjen er oppe. Passord er aldri med.
Samtalehistorikk: GET /history
Nyeste først, 100 oppføringer med mindre ?limit= sier noe annet. ?missed=true returnerer bare tapte samtaler, ?declined=true bare samtalene denne telefonen avviste.
| Felt | Betydning |
|---|---|
id | Historikkoppføringens egen identifikator. Det er ikke samtale-id fra /calls og fra webhooker; seance_id knytter de to sammen. |
outcome | Hovedklassifiseringen: answered, missed, declined eller failed. |
answered | true eller false. |
duration_s | 0 for en samtale som aldri ble koblet opp. |
number, uri | Den andre parten, som nummer og som SIP-adresse. |
name | Fra Kontakter hvis nummeret er kjent, ellers tomt. Match på number, ikke på dette. |
dialed | Sifrene som ble slått, for en utgående samtale; tomt for en innkommende. |
account, account_id | Linjen samtalen gikk over. |
reason | Hvordan den sluttet: local-hangup, remote-hangup, cancelled… |
answered_by | no hvis en person svarte; ellers det som svarte på samtalen. |
Kontakter: GET /contacts
Hver kontakt har sin id, name, number og linjen den hører til, account_id og account; en tom account betyr at kontakten ikke er knyttet til en linje.
Opptak
Opptak og utskrifter deles ikke ut som JSON. API-et tilbyr dem som HTML-sider, /ui og /ui/recordings/{id}: lenk til disse sidene fra CRM-et ditt i stedet for å flytte lyd rundt. Lenken åpnes på maskinen som har opptaket, og lyden forlater den aldri.
Taksonomi og innstillinger
Hver oppføring i /taxonomy har en fast code, en title og en description på grensesnittspråket, en kind (category, tag eller red_flag) og, for signaler, en severity. Match på code, aldri på title: titlene kommer på språket telefonen er satt til. En oppføring med retired: true beholdes slik at eldre samtaler fortsatt kan slås opp; den gis ikke lenger til nye samtaler. Last inn taksonomien én gang ved oppstart for å koble telefonens ord til dine egne felter.
/settings returnerer konfigurasjonen unntatt hemmelighetene: lydenheter og lydstyrker, kodekprioritet, utseende og språk, oppstart, snarveier, diagnosenivået og tilstanden til begge integrasjonene — nyttig for et støtteverktøy som må sjekke en arbeidsstasjon uten skjermdeling. api.disabled viser tilgangsgruppene som er av, og webhooks.silenced hendelsene som er av; tomme lister betyr at alt er på. Den inneholder aldri SIP-passordet, API-nøkkelen eller webhookens hodeverdi.
Feil
Hver feil er JSON med én enkelt nøkkel error, ment for mennesker, ikke for maskinell tolking.
| Status | Innhold | Betydning |
|---|---|---|
| 404 | {"error":"no such endpoint"} | Stien finnes ikke, eller tilgangsgruppen er av; begge gir med vilje det samme svaret. |
| 405 | {"error":"that endpoint does not take this method"} | Stien finnes, men tar ikke denne metoden: for eksempel POST /settings i stedet for PUT. |
| 401 | {"error":"writing needs a token, and none is configured"} | Et endepunkt som endrer det som er lagret, på en telefon der feltet Nøkkel er tomt. Fyll det ut under Lokal styring. |
| 401 | {"error":"this endpoint needs the authorization token"} | Et endepunkt som endrer det som er lagret, uten riktig nøkkel. |
| 404 | {"error":"no contact with that id"} | Stien er riktig, identifikatoren er det ikke. |
| 400 | {"error":"no call with that id"} | Samtalen er slutt, eller har aldri eksistert. |
| 400 | {"error":"a call needs a number"} | POST /calls uten et nummer. Ingenting ble ringt. |
| 400 | {"error":"no digits to send"} | POST /calls/{id}/dtmf uten sifre. |
| 400 | {"error":"a transfer needs a target"} | POST /calls/{id}/transfer uten et mål. |
| 400 | {"error":"the account this call is on is no longer set up"} | Kontoen for samtalen ble fjernet under samtalen, så målet kan ikke fullføres. Ingenting ble sendt til sentralen. |
Avviste forespørsler telles i api_requests_refused_total, så en integrasjon som feiler i det stille, viser seg i målingene og ikke bare i dine egne logger.
Målinger
GET /metrics returnerer hver av telefonens tellere, hver med en hjelpetekst. Samle dem inn med Prometheus, eller les dem for hånd.
| Teller | Teller |
|---|---|
calls_incoming_total | Mottatte innkommende samtaler. |
calls_outgoing_total | Ringte utgående samtaler. |
calls_answered_total | Samtaler som ble besvart. |
calls_missed_total | Innkommende samtaler som ikke ble besvart. |
calls_declined_total | Samtaler avvist her eller av den andre siden. |
calls_failed_total | Samtaler som ikke kunne kobles opp. |
registrations_succeeded_total | Vellykkede SIP-registreringer. |
registrations_failed_total | SIP-registreringer som ble avvist eller tidsavbrutt. |
webhooks_delivered_total | Webhooker mottakeren godtok. |
webhooks_failed_total | Webhooker som ble avvist eller ikke levert. |
webhooks_dropped_total | Webhooker som ble kastet fordi køen var full. |
api_requests_total | Forespørsler håndtert av API-et. |
api_requests_refused_total | Avviste forespørsler: feil nøkkel, gruppe av eller ukjent sti. |
Oppdatere en eldre integrasjon
Tidligere versjoner brukte navn i camelCase og korte identifikatorer. accountId heter nå account_id, startedAt heter callstart_ts, durationSeconds heter duration_s, answeredBy heter answered_by, og webhookfeltet at heter event_ts. Samtaler og kontoer identifiseres bare med UUID: runtimeId og identifikatorer som call-3 eller account-2 returneres eller godtas ikke lenger.
Når det ikke virker
| Symptom | Hva du bør sjekke |
|---|---|
Tilkobling avvist på 127.0.0.1:8377 | Lokal styring er av, telefonen kjører ikke, eller porten er endret. |
404 {"error":"no such endpoint"} for en sti på denne siden | Tilgangsgruppen er av. |
Lesing virker, skriving avvises med 401 | Endepunktene som endrer lagrede data, krever nøkkelen i hodet Authorization, og feltet Nøkkel på telefonen må fylles ut først. |
| Kategorititlene er ikke på engelsk | Titlene følger grensesnittspråket. Match på code fra /taxonomy. |
accountId, startedAt eller at mangler | Integrasjonen ble skrevet for de tidligere navnene; se over. |
Ved et problem med registrering eller selve samtalen åpner du Diagnostikk.