Hendelsesloggen og strømmen

Webhook, strøm eller logg?

• Webhooks passer når du har en offentlig adresse og vil at vi skal komme til deg.
• Strømmen passer når du ikke kan ta imot innkommende kall, for eksempel bak en brannmur, eller vil ha hendelsene uten at vi må nå deg.
• Loggen passer for å ta igjen det du gikk glipp av, og for jobber som kjører av og til.

En hendelse har den samme id-en (evt_…) i alle tre. Du kan bruke flere samtidig og fjerne duplikater med id-en.

Hendelsesloggen

Hver hendelse har en position. Posisjonene øker i den rekkefølgen hendelsene ble lagret, uten hull. Filtrerer du på type eller profil, hopper svaret over posisjonene du ikke ba om. Lagre den siste posisjonen du har behandlet, og spør etter alt etter den:

curl "https://api.telkit.no/v1/events?after=1200&limit=100" \  -H "Authorization: Bearer $TELKIT_API_KEY"

const response = await fetch("https://api.telkit.no/v1/events?after=1200&limit=100", {  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,  },});const answer = await response.json();

• Svaret har events (eldste først), next, head og floor. Er next ikke null, er det mer: send den som after.
• Uten after starter du ved den eldste hendelsen loggen har. limit: 0 gir bare head, nyttig når du vil starte fra nå.
• Loggen tar vare på hendelser i 30 dager.

curl "https://api.telkit.no/v1/events?after=1200&types=call.ended" \  -H "Authorization: Bearer $TELKIT_API_KEY"

const response = await fetch("https://api.telkit.no/v1/events?after=1200&types=call.ended", {  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,  },});const answer = await response.json();

Én hendelse etter id:

curl "https://api.telkit.no/v1/events/evt_0199e4aa8b6e7c5f97a4ce9f6bacbd54" \  -H "Authorization: Bearer $TELKIT_API_KEY"

const response = await fetch("https://api.telkit.no/v1/events/evt_0199e4aa8b6e7c5f97a4ce9f6bacbd54", {  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,  },});const answer = await response.json();

Når posisjonen din er for gammel

Er after lavere enn floor, er noen av hendelsene etter den slettet. Da svarer vi 409 med koden resume_too_old i stedet for å gi deg en liste med et hull du ikke ser. Les fra floor, eller uten after, og sjekk tilstanden mot dine egne data.

Hendelsesstrømmen

GET /v1/event-stream holder forbindelsen åpen og sender hendelsene som server-sent events så snart de er lagret. Nøkkelen trenger tilgangen events:read.

curl -N "https://api.telkit.no/v1/event-stream?types=call.ended&types=sms.status" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Accept: text/event-stream"

const response = await fetch("https://api.telkit.no/v1/event-stream?types=call.ended&types=sms.status", {  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    Accept: "text/event-stream",  },});const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();for (;;) {  const { value, done } = await reader.read();  if (done) break;  // Each event is "id:", "event:" and "data:" lines, ended by an empty line.  console.log(value);}

Uten after og Last-Event-ID får du bare hendelser som kommer etter at du koblet til. Hver hendelse er tre linjer: id er posisjonen, event er navnet, og data er hendelsen slik GET /v1/events gir den.

id: 1201event: call.endeddata: {"id":"evt_0199e4aa8b6e7c5f97a4ce9f6bacbd54","position":1201,"type":"call.ended","version":1,"mode":"live","profileId":"0199e4a2-7c1b-7d3e-9a41-5f2c8b6d1e07","occurredAt":"2026-10-14T09:15:02.118Z","data":{…}} event: heartbeatdata: {} 

• Er det stille, sender vi heartbeat hvert 15. sekund, så du vet at forbindelsen lever.
• En strøm er åpen i inntil 60 minutter. Når vi starter serveren på nytt, stenger vi strømmene pent. Koble til igjen med Last-Event-ID i begge tilfeller.
• Nøkkelen, tilgangen og profilen blir sjekket på nytt hvert 30. sekund. En nøkkel som er trukket tilbake, stenger strømmen.
• En nøkkel får bare hendelser i sin egen modus, test eller live.

Fortsett der du slapp

1. Lagre posisjonen (id) for hver hendelse du har behandlet.
2. Når forbindelsen stenger, koble til igjen med den som Last-Event-ID.
3. Får du hendelsen error med resume_too_old, er posisjonen din eldre enn loggen. Strømmen stenger. Les fra floor med GET /v1/events, sjekk mot dine egne data, og åpne strømmen igjen fra der du kom.

curl -N "https://api.telkit.no/v1/event-stream" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Accept: text/event-stream" \  -H "Last-Event-ID: 1200"

const response = await fetch("https://api.telkit.no/v1/event-stream", {  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    Accept: "text/event-stream",    "Last-Event-ID": "1200",  },});const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();for (;;) {  const { value, done } = await reader.read();  if (done) break;  // Each event is "id:", "event:" and "data:" lines, ended by an empty line.  console.log(value);}

event: errordata: {"code":"resume_too_old","floor":950,"head":4210} 

Når strømmen ikke åpner