Gå til hovedindholdet

Lokalt REST-API

AI Softphone har et REST-API til CTI-integration: et program på samme computer kan foretage og styre opkald, læse kontakter, opkaldshistorik og SIP-konti og følge de igangværende opkald. Intet SDK, ingen mellemmand i skyen og ingen lytter, der er eksponeret mod netværket. Forespørgsler og svar er JSON, så curl eller en hvilken som helst HTTP-klient er nok.

API'et er slået fra efter installationen; intet lytter, før du slår det til. Derefter lytter det kun på loopback-grænsefladen — en lille webgrænseflade, der kun svarer denne computer — og kan ikke nås fra kontornetværket, et VPN eller en anden maskine.

Brug API'et, når dit program har brug for data fra telefonen eller skal styre et opkald. Brug webhooks, når det skal reagere på opkald, mens de sker, uden at spørge igen og igen. De fleste integrationer bruger begge; de er uafhængige af hinanden.

Slå det til​

Åbn Indstillinger → Integration, og gå til Lokal styring.

  1. Slå Lad andre programmer på denne computer styre telefonen til. Serveren starter med det samme.
  2. Behold standard-Port, 8377, medmindre et andet program allerede bruger den.
  3. Sæt eventuelt en Nøgle. Når den er gemt, viser feltet Gemt — skriv for at erstatte det.
  4. Vælg under Adgang de grupper, der skal åbnes: Kontakter, Opkaldshistorik, Opkald, og styringen af dem, Konti, Indstillinger, Tællere (målingerne). En gruppe, der er slået fra, filtreres ikke, men stilles slet ikke til rådighed.
  5. Prøv det: curl http://127.0.0.1:8377/accounts. Er svaret JSON, virker API'et.

Der installeres ingen separat tjeneste, og der kræves ingen genstart. Den del af programmet, der gør dette, kan slås fra under Moduler (Integration).

API'ets egen side​

Åbn API'ets egen side åbner http://127.0.0.1:8377 i en browser. Adressen svarer med en liste over alt, hvad den stiller til rådighed, på engelsk; de adresser, der læser noget, er links, du kan følge.

Adgang og nøglen​

Hvad et program må, afhænger af, om det ændrer gemte data, ikke af, om det læser:

  • Uden en nøgle må ethvert program på computeren læse alt i de åbnede grupper og styre opkald: foretage, besvare, lægge på, parkere, genoptage, viderestille og sende DTMF.
  • Med nøglen i hovedet Authorization må det også bruge de endepunkter, der ændrer det gemte. Uden nøglen vises disse endepunkter ikke på API'ets egen side, og de svarer 401. Er der slet ingen nøgle sat, kan intet ændre det gemte.

Nøglen gemmes i computerens nøglering, ikke i indstillingsfilen, og returneres aldrig af /settings.

forsigtig

Uden en nøgle kan ethvert program, der kører på denne computer, styre telefonen, også besvare opkald. På en personlig arbejdsstation er det som regel acceptabelt. På en delt eller administreret maskine bør du sætte en nøgle og behandle den som enhver anden adgangskode. Nøglen beskytter kun de forespørgsler, der ændrer gemte data, ikke opkaldene: vil du holde andre programmer væk fra opkaldene, så slå Opkald, og styringen af dem fra under Adgang.

Endepunkter​

Grundadressen er http://127.0.0.1:8377. Endepunkterne nedenfor kræver ingen nøgle.

MetodeStiGør
GET/metricsTællerne i Prometheus-format.
GET/uiListen over optagelser som en HTML-side.
GET/ui/recordings/{id}En optagelse med dens udskrift som en HTML-side.
GET/ui/recordings/{id}/audioLyden til siden ovenfor.
GET/contactsKontakterne.
GET/contacts/{id}En enkelt kontakt.
GET/historyOpkaldshistorikken, nyeste først. Accepterer ?limit=, ?missed=true og ?declined=true.
GET/callsDe igangværende opkald.
POST/callsForetager et opkald: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerBesvarer et opkald.
POST/calls/{id}/hangupLægger et opkald på.
POST/calls/{id}/holdParkerer et opkald.
POST/calls/{id}/resumeTager det ud af parkering.
POST/calls/{id}/dtmfSender toner: {"digits": "..."}.
POST/calls/{id}/transferViderestiller opkaldet: {"target": "..."}.
GET/accountsSIP-kontiene og deres registreringstilstand. Aldrig en adgangskode.
GET/settingsHele konfigurationen uden hemmelighederne.
GET/taxonomyKategorier, etiketter og signaler med deres koder.

Endepunkter, der kræver nøglen​

De ændrer det gemte, så hver forespørgsel skal have nøglen med i hovedet Authorization. API'ets egen side viser dem kun for en forespørgsel, der har den med.

MetodeStiGør
POST/contactsTilføjer 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 ét opkald i opkaldsloggen.
DELETE/historyGlemmer hele opkaldsloggen. Det kan ikke fortrydes.
PUT/accounts/{id}Erstatter indstillingerne for en konto. Adgangskoden er ikke blandt dem.
PUT/settingsErstatter indstillingerne.

Hver identifikator er en UUID udstedt af telefonen: et opkalds id kommer fra /calls eller fra svaret på POST /calls, en kontos id fra /accounts.

Feltnavne er i snake_case, og endelsen fortæller typen: _id er en reference til en UUID, _ts er et tidspunkt i Unix-millisekunder (UTC), _s er en varighed i sekunder. Det samme gælder for webhooks; kun /settings har sine egne navne. I REST-API'et er disse værdier JSON-tal, og et ukendt tidspunkt er null.

Eksempel: foretage et opkald​

POST /calls foretager et udgående opkald. Indholdet er JSON med det number, der skal ringes til, og eventuelt account_id for den konto, der 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 det nye opkalds identifikator:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number er påkrævet. Uden det er svaret 400 {"error":"a call needs a number"}, og der ringes ikke op.
  • Nummeret fuldendes på den valgte konto, som opkaldsfeltet fuldender det: 1020 sendes som sip:1020@pbx.example.com. POST /calls/{id}/transfer fuldender sit target på samme måde; et mål, der allerede har et skema eller et @, sendes, som det er.
  • account_id er valgfrit; tag det fra GET /accounts. Uden det går opkaldet ud på den konto, der er valgt i hovedvinduet.
  • Brug id i /calls/{id}/…: hangup, hold, resume, dtmf og transfer. Webhooks for dette opkald bærer samme id.

Fra en webside: klik for at ringe​

En side, der kalder 127.0.0.1, når den computer, browseren kører på — den samme, telefonen kører på —, så en klik-for-at-ringe-knap i et CRM behøver 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);
}

Hvad svarene indeholder​

Igangværende opkald: GET /calls​

Hvert opkald har sit 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 (parkeret af denne telefon), onhold (parkeret af den anden part), conference eller ended. Når flere gælder, vinder conference over hold, og hold over onhold.
  • muted siger, om mikrofonen er slået fra i opkaldet; at slå lyden fra ændrer ikke state.
  • seance_id er samtalen: opkald, der er forbundet ved en viderestilling, en konsultation eller en konference, deler den.
  • event_ts er, hvornår svaret blev lavet. Sammenlign det med callstate_ts for at se, hvor længe opkaldet har været i sin tilstand, uden at stole på dit eget ur.

Konti: GET /accounts​

Hver konto har sit id (account_id alle andre steder), sine indstillinger — transport (udp, tcp eller tls), port, registrar, outbound_proxy, expiry_s og andre —, om den er enabled, og sin state på omstillingsanlægget: registered, mens linjen er oppe. Adgangskoder er aldrig med.

Opkaldshistorik: GET /history​

Nyeste først, 100 poster, medmindre ?limit= siger andet. ?missed=true returnerer kun ubesvarede opkald, ?declined=true kun de opkald, denne telefon afviste.

FeltBetydning
idHistorikpostens egen identifikator. Det er ikke opkalds-id fra /calls og fra webhooks; seance_id forbinder de to.
outcomeHovedklassificeringen: answered, missed, declined eller failed.
answeredtrue eller false.
duration_s0 for et opkald, der aldrig blev forbundet.
number, uriDen anden part som nummer og som SIP-adresse.
nameFra Kontakter, hvis nummeret er kendt, ellers tomt. Match på number, ikke på dette.
dialedDe tastede cifre ved et udgående opkald; tomt ved et indgående.
account, account_idDen linje, opkaldet gik over.
reasonHvordan det sluttede: local-hangup, remote-hangup, cancelled…
answered_byno, hvis en person besvarede det; ellers det, der besvarede opkaldet.

Kontakter: GET /contacts​

Hver kontakt har sit id, name, number og den linje, den hører til, account_id og account; en tom account betyder, at kontakten ikke er knyttet til en linje.

Optagelser​

Optagelser og udskrifter udleveres ikke som JSON. API'et stiller dem til rådighed som HTML-sider, /ui og /ui/recordings/{id}: link til disse sider fra dit CRM i stedet for at flytte lyd rundt. Linket åbner på den computer, der gemmer optagelsen, og lyden forlader den aldrig.

Taksonomi og indstillinger​

Hver post i /taxonomy har en fast code, en title og en description på brugerfladens sprog, en kind (category, tag eller red_flag) og, for signaler, en severity. Match på code, aldrig på title: titler kommer på det sprog, telefonen er sat til. En post med retired: true beholdes, så ældre opkald stadig kan slås op; den gives ikke længere til nye opkald. Indlæs taksonomien én gang ved opstart for at koble telefonens ord til dine egne felter.

/settings returnerer konfigurationen undtagen hemmelighederne: lydenheder og lydstyrker, codec-prioritet, udseende og sprog, opstart, genveje, diagnoseniveauet og tilstanden for begge integrationer — nyttigt for et supportværktøj, der skal tjekke en arbejdsstation uden skærmdeling. api.disabled viser de adgangsgrupper, der er slået fra, og webhooks.silenced de hændelser, der er slået fra; tomme lister betyder, at alt er slået til. Den indeholder aldrig SIP-adgangskoden, API-nøglen eller webhookens hovedværdi.

Fejl​

Hver fejl er JSON med en enkelt nøgle error, beregnet til mennesker, ikke til maskinel fortolkning.

StatusIndholdBetydning
404{"error":"no such endpoint"}Stien findes ikke, eller dens adgangsgruppe er slået fra; begge giver med vilje samme svar.
405{"error":"that endpoint does not take this method"}Stien findes, men tager ikke denne metode: for eksempel POST /settings i stedet for PUT.
401{"error":"writing needs a token, and none is configured"}Et endepunkt, der ændrer det gemte, på en telefon, hvor feltet Nøgle er tomt. Udfyld det under Lokal styring.
401{"error":"this endpoint needs the authorization token"}Et endepunkt, der ændrer det gemte, uden den rigtige nøgle.
404{"error":"no contact with that id"}Stien er rigtig, identifikatoren er ikke.
400{"error":"no call with that id"}Opkaldet er slut eller har aldrig eksisteret.
400{"error":"a call needs a number"}POST /calls uden et nummer. Der blev ikke ringet op.
400{"error":"no digits to send"}POST /calls/{id}/dtmf uden cifre.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer uden et mål.
400{"error":"the account this call is on is no longer set up"}Opkaldets konto blev fjernet under opkaldet, så målet kan ikke fuldendes. Intet blev sendt til omstillingsanlægget.

Afviste forespørgsler tælles i api_requests_refused_total, så en integration, der fejler i stilhed, viser sig i målingerne og ikke kun i dine egne logge.

Målinger​

GET /metrics returnerer hver af telefonens tællere, hver med en hjælpetekst. Indsaml dem med Prometheus, eller læs dem manuelt.

TællerTæller
calls_incoming_totalModtagne indgående opkald.
calls_outgoing_totalForetagne udgående opkald.
calls_answered_totalOpkald, der blev besvaret.
calls_missed_totalIndgående opkald, der ikke blev besvaret.
calls_declined_totalOpkald afvist her eller af den anden side.
calls_failed_totalOpkald, der ikke kunne oprettes.
registrations_succeeded_totalVellykkede SIP-registreringer.
registrations_failed_totalSIP-registreringer, der blev afvist eller udløb.
webhooks_delivered_totalWebhooks, modtageren accepterede.
webhooks_failed_totalWebhooks, der blev afvist eller ikke leveret.
webhooks_dropped_totalWebhooks smidt væk, fordi køen var fuld.
api_requests_totalForespørgsler håndteret af API'et.
api_requests_refused_totalAfviste forespørgsler: forkert nøgle, gruppe slået fra eller ukendt sti.

Opdatere en ældre integration​

Tidligere versioner brugte navne i camelCase og korte identifikatorer. accountId hedder nu account_id, startedAt hedder callstart_ts, durationSeconds hedder duration_s, answeredBy hedder answered_by, og webhookfeltet at hedder event_ts. Opkald og konti identificeres kun ved UUID: runtimeId og identifikatorer som call-3 eller account-2 returneres eller accepteres ikke længere.

Når det ikke virker​

SymptomHvad du skal tjekke
Forbindelse afvist på 127.0.0.1:8377Lokal styring er slået fra, telefonen kører ikke, eller porten er ændret.
404 {"error":"no such endpoint"} for en sti på denne sideDens adgangsgruppe er slået fra.
Læsning virker, skrivning afvises med 401De endepunkter, der ændrer gemte data, kræver nøglen i hovedet Authorization, og feltet Nøgle på telefonen skal udfyldes først.
Kategorititler er ikke på engelskTitler følger brugerfladens sprog. Match på code fra /taxonomy.
accountId, startedAt eller at manglerIntegrationen blev skrevet til de tidligere navne; se ovenfor.

Ved et problem med registrering eller selve opkaldet skal du åbne Diagnostik.