Send SMS fra ditt eget system

1. En bedrift og en profil. En profil er en avsender i bedriften din, for eksempel «nettbutikken» eller «kundeservice». Den har et kortnavn du bruker i API-et, og SMS må være slått på for den.
2. En API-nøkkel. Du lager den i dashbordet. En testnøkkel sender ingenting og koster ingenting, men svarer som en ekte nøkkel. Bruk den mens du bygger.
3. Saldo. telkit trekker prisen fra saldoen bedriften har fylt på. En SMS-enhet koster 0,75 kr.

Vil du sende med firmanavnet som avsender, må navnet være godkjent først. Les mer i guiden om avsender-ID.

Den minste forespørselen har profil, mottaker og tekst:

curl https://api.telkit.no/v1/sms \
  -H "Authorization: Bearer $TELKIT_API_KEY" \
  -H "Idempotency-Key: ordre-10234-hentes" \
  -H "Content-Type: application/json" \
  -d '{
  "profile": "nettbutikken",
  "to": "+4791234567",
  "text": "Hei! Pakken din er klar til henting."
}'

profile

Profilens kortnavn. Du kan bruke profileId i stedet.

to

Et norsk mobilnummer. Skriv det gjerne i E.164-format, som +4791234567. Mellomrom går også.

text eller templateId

Selve meldingen, eller en mal fra profilen med verdiene i variables. Bruk én av dem. Teksten kan være lang, men hver SMS-enhet koster for seg.

sender

Avsenderen for akkurat denne meldingen. Uten den bruker profilen sin standardavsender.

scheduledAt

Et tidspunkt fram i tid. Da holder telkit meldingen til da, og du kan avbryte den.

Svaret kommer med en gang:

{
  "id": "<meldingens id>",
  "state": "queued",
  "units": 1,
  "priceOre": 75,
  "scheduledAt": null,
  "testMode": false
}

priceOre er prisen i øre uten mva. units er antall SMS-enheter teksten trenger. Statusen queued betyr at telkit har tatt imot meldingen og skal sende den.

Fordi nettverk svikter midt i et kall. Brytes forbindelsen etter at telkit fikk forespørselen, men før svaret kom fram, vet du ikke om meldingen ble sendt. Med en Idempotency-Key kan du trygt sende den samme forespørselen på nytt: meldingen blir bare sendt én gang.

Lag nøkkelen fra noe som er unikt for handlingen i ditt system, for eksempel ordrenummeret og hva meldingen gjelder. Bruk den samme nøkkelen når du prøver igjen, og en ny nøkkel for en ny melding. telkit avviser en sending uten nøkkel. Les mer om idempotens.

Feltet sender har tre former: {"kind":"text","name":"…"} for et godkjent avsendernavn, {"kind":"dedicated"} for profilens eget nummer og {"kind":"reply_number"} for et nummer mottakeren kan svare til.

{
  "profile": "nettbutikken",
  "to": "+4791234567",
  "text": "Timen din er i morgen kl. 10.",
  "sender": {
    "kind": "text",
    "name": "Tannlegen"
  },
  "scheduledAt": "2026-10-20T08:00:00+02:00"
}

En planlagt melding kan avbrytes med POST /v1/sms/{id}/cancel til den er sendt. Prisen holdes av når du planlegger, og frigjøres når du avbryter.

Vil du vite prisen før du sender, bruker du POST /v1/sms/quote med den samme teksten og avsenderen. Svaret gir antall tegn, enheter og pris, og sender ingenting.

Svaret på sendingen betyr bare at telkit har tatt imot meldingen. Om den kom fram, avgjøres i mobilnettet etterpå. Den beskjeden kommer som en leveringsrapport, og telkit gir den videre som hendelsen sms.status til webhooken din:

sent

Meldingen er sendt til mobilnettet.

delivered

Mobilnettet har levert meldingen til telefonen.

failed

Meldingen kom ikke fram. errorDesc har operatørens begrunnelse.

Hendelsen har også meldingens id, mottakeren, antall enheter og prisen. Du kan i tillegg lese en melding med GET /v1/sms/{id} eller hente loggen med GET /v1/sms, men webhooken er raskere og koster deg ingen spørringer.

Andre hendelser du kan abonnere på: sms.received når noen svarer, sms.optedOut når noen svarer STOPP, og sms.optedIn når de melder seg på igjen.

Du registrerer en https-adresse i dashbordet eller med POST /v1/webhook-endpoints, og velger hvilke hendelser den skal få. Du får en hemmelig nøkkel én gang.

• Sjekk signaturen. Hver levering er signert etter Standard Webhooks-formatet med den hemmelige nøkkelen. Kast det som ikke har gyldig signatur.
• Svar raskt med 2xx. Gjør arbeidet i en kø etterpå. Svarer du ikke, prøver telkit igjen.
• Tål duplikater. Den samme hendelsen kan komme mer enn én gang. Bruk hendelsens id til å se om du har behandlet den før.

Feiler leveringene i fem dager, eller svarer adressen 410 Gone, stopper telkit leveringene til den. Du kan se de siste forsøkene og sende mislykkede leveringer på nytt fra dashbordet eller API-et.

Når telkit avviser en sending, har svaret en kode. De vanligste:

recipient_invalid

Mottakeren er ikke et norsk mobilnummer (422).

recipient_opted_out

Mottakeren har svart STOPP til denne profilen (422). Ikke prøv igjen.

sms_too_long

Teksten er lengre enn en SMS kan være (422).

sender_not_approved

Avsendernavnet er ikke godkjent.

insufficient_credits

Saldoen dekker ikke meldingen (402). Fyll på og send igjen.

schedule_in_past

scheduledAt er ikke fram i tid (422).