Gå til hovedinnholdet

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.

  1. Slå på La andre programmer på denne maskinen styre telefonen. Serveren starter med én gang.
  2. Behold standard Port, 8377, med mindre et annet program allerede bruker den.
  3. Sett eventuelt en Nøkkel. Når den er lagret, viser feltet Lagret — skriv for å erstatte det.
  4. 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.
  5. 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 Authorization kan det også bruke endepunktene som endrer det som er lagret. Uten nøkkelen vises ikke disse endepunktene på API-ets egen side, og de svarer 401. 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.

forsiktig

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.

MetodeStiGjør
GET/metricsTellerne, i Prometheus-format.
GET/uiListen over opptak, som en HTML-side.
GET/ui/recordings/{id}Et opptak med utskriften, som en HTML-side.
GET/ui/recordings/{id}/audioLyden til siden over.
GET/contactsKontaktene.
GET/contacts/{id}Én enkelt kontakt.
GET/historySamtalehistorikken, nyeste først. Godtar ?limit=, ?missed=true og ?declined=true.
GET/callsSamtalene som pågår.
POST/callsRinger en samtale: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerSvarer på en samtale.
POST/calls/{id}/hangupLegger på en samtale.
POST/calls/{id}/holdSetter en samtale på vent.
POST/calls/{id}/resumeTar den av vent.
POST/calls/{id}/dtmfSender toner: {"digits": "..."}.
POST/calls/{id}/transferSetter over samtalen: {"target": "..."}.
GET/accountsSIP-kontoene og registreringstilstanden deres. Aldri et passord.
GET/settingsHele konfigurasjonen, uten hemmelighetene.
GET/taxonomyKategorier, 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.

MetodeStiGjør
POST/contactsLegger 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/historyGlemmer hele samtaleloggen. Det kan ikke angres.
PUT/accounts/{id}Erstatter innstillingene for en konto. Passordet er ikke blant dem.
PUT/settingsErstatter 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" }
  • number er påkrevd. Uten det er svaret 400 {"error":"a call needs a number"}, og ingenting ringes.
  • Nummeret fullføres på den valgte kontoen slik nummerfeltet fullfører det: 1020 sendes som sip:1020@pbx.example.com. POST /calls/{id}/transfer fullfører sitt target på samme måte; et mål som allerede har et skjema eller en @, sendes som det er.
  • account_id er valgfritt; ta det fra GET /accounts. Uten det går samtalen ut på kontoen som er valgt i hovedvinduet.
  • Bruk id i /calls/{id}/…: hangup, hold, resume, dtmf og transfer. Webhookene for denne samtalen har samme id.

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.

  • state er dialing, ringing-out, ringing-in, active, hold (satt på vent av denne telefonen), onhold (satt på vent av den andre parten), conference eller ended. Når flere gjelder, vinner conference over hold, og hold over onhold.
  • muted sier om mikrofonen er slått av i samtalen; å slå av lyden endrer ikke state.
  • seance_id er samtalen i videre forstand: samtaler som er knyttet sammen ved en overføring, en konsultasjon eller en konferanse, deler den.
  • event_ts er når svaret ble laget. Sammenlign den med callstate_ts for å 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.

FeltBetydning
idHistorikkoppføringens egen identifikator. Det er ikke samtale-id fra /calls og fra webhooker; seance_id knytter de to sammen.
outcomeHovedklassifiseringen: answered, missed, declined eller failed.
answeredtrue eller false.
duration_s0 for en samtale som aldri ble koblet opp.
number, uriDen andre parten, som nummer og som SIP-adresse.
nameFra Kontakter hvis nummeret er kjent, ellers tomt. Match på number, ikke på dette.
dialedSifrene som ble slått, for en utgående samtale; tomt for en innkommende.
account, account_idLinjen samtalen gikk over.
reasonHvordan den sluttet: local-hangup, remote-hangup, cancelled…
answered_byno 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.

StatusInnholdBetydning
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.

TellerTeller
calls_incoming_totalMottatte innkommende samtaler.
calls_outgoing_totalRingte utgående samtaler.
calls_answered_totalSamtaler som ble besvart.
calls_missed_totalInnkommende samtaler som ikke ble besvart.
calls_declined_totalSamtaler avvist her eller av den andre siden.
calls_failed_totalSamtaler som ikke kunne kobles opp.
registrations_succeeded_totalVellykkede SIP-registreringer.
registrations_failed_totalSIP-registreringer som ble avvist eller tidsavbrutt.
webhooks_delivered_totalWebhooker mottakeren godtok.
webhooks_failed_totalWebhooker som ble avvist eller ikke levert.
webhooks_dropped_totalWebhooker som ble kastet fordi køen var full.
api_requests_totalForespørsler håndtert av API-et.
api_requests_refused_totalAvviste 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​

SymptomHva du bør sjekke
Tilkobling avvist på 127.0.0.1:8377Lokal styring er av, telefonen kjører ikke, eller porten er endret.
404 {"error":"no such endpoint"} for en sti på denne sidenTilgangsgruppen er av.
Lesing virker, skriving avvises med 401Endepunktene 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å engelskTitlene følger grensesnittspråket. Match på code fra /taxonomy.
accountId, startedAt eller at manglerIntegrasjonen ble skrevet for de tidligere navnene; se over.

Ved et problem med registrering eller selve samtalen åpner du Diagnostikk.