En variabel er en plassholder i teksten til en melding. Hver mottaker får sin egen verdi på plassen – et navn, et firmanavn, et ordrenummer. Slik sender du én tekst til tusenvis av mennesker, og hver av dem leser en melding som er skrevet til akkurat dem. Variabler skrives på samme måte i en kampanje og i API-et.

## Slik skriver du en variabel

En variabel er et navn i vinkelparenteser, for eksempel `<first_name>`. Når meldingen sendes, erstattes den med verdien du har for den mottakeren:

| meldingstekst | hva mottakeren får |
|:--|:--|
| `Hei <first_name>, bestillingen din er på vei.` | `Hei Ola, bestillingen din er på vei.` |

- **Navnet må stemme nøyaktig.** Store og små bokstaver og mellomrom betyr noe – verken `<First_Name>` eller `< first_name >` erstattes med verdien for `first_name`.
- **En tom verdi er det samme som ingen verdi.** Tom tekst eller bare mellomrom regnes som en manglende verdi – hva som da skjer, er beskrevet i [Når verdien mangler](#nar-verdien-mangler).

> [!WARNING]
> Alt som er skrevet som `<noe:noe>`, `<noe=tall>` eller `<noe|filter>`, tolkes alltid som en variabel, selv om du ikke har noen slik variabel, og det endres i meldingen som sendes. Å skrive det som `&lt;` hjelper heller ikke. En enkeltstående `<` eller `<b>` blir stående som den er.

## Når verdien mangler

Når du ikke har noen verdi for en mottaker, blir variabelen stående i meldingen **bokstavelig** – mottakeren får `Hei <first_name>, …`. Det unngår du med en standardverdi som skrives etter et kolon:

| skrivemåte | hva en mottaker uten verdi får |
|:--|:--|
| `<first_name>` | bokstavelig `<first_name>` |
| `<first_name:der>` | reserveteksten `der` |
| `<first_name:>` | ingenting – variabelen utelates |

En mottaker du har en verdi for, får sin egen verdi i alle tre tilfellene.

> [!TIP]
> Bruk en variabel uten standardverdi bare der du har data for hver eneste mottaker. Ellers legger du til en reservetekst eller lar variabelen utelates.

## Filtre

Et filter justerer verdien som settes inn – det gjør den om til store bokstaver, fjerner mellomrom, lager en tiltaleform av et navn eller holder øye med lengden. Du skriver det etter en loddrett strek rett etter variabelnavnet: `<first_name|upper>`. Du kan skrive flere filtre etter hverandre, og de brukes fra venstre mot høyre: `<city|trim|capitalize>` – mer om dette i [Kjeding av filtre](#kjeding-av-filtre).

### Store og små bokstaver

| skrivemåte | hva filteret gjør | eksempel |
|:--|:--|:--|
| `<last_name\|upper>` | gjør hele verdien om til store bokstaver | `Ola Nordmann` → `OLA NORDMANN` |
| `<last_name\|lower>` | gjør hele verdien om til små bokstaver | `Ola Nordmann` → `ola nordmann` |
| `<last_name\|first_upper>` | gjør den første bokstaven stor og lar resten være uendret | `ola nordmann` → `Ola nordmann` |
| `<last_name\|capitalize>` | lar hvert ord begynne med stor bokstav, alle andre bokstaver blir små | `oLA nORDMANN` → `Ola Nordmann` |

### Tekstjusteringer

| skrivemåte | hva filteret gjør | eksempel |
|:--|:--|:--|
| `<last_name\|trim>` | fjerner mellomrom i starten og på slutten | `" Ola Nordmann "` → `"Ola Nordmann"` |
| `<last_name\|ascii>` | fjerner diakritiske tegn | `Šťastný` → `Stastny` |
| `<city\|webalize>` | gjør verdien om til en form for en nettadresse – uten diakritiske tegn, med små bokstaver og med ordene bundet sammen med bindestrek | `Ústí nad Labem` → `usti-nad-labem` |
| `<company_name\|word:1>` | velger ett ord ut fra plasseringen; når verdien ikke har så mange ord, settes ingenting inn | `Kytary Novák` → `Kytary` |
| `<company_name\|initial>` | initialer – den første bokstaven i hvert ord, stor og etterfulgt av punktum | `Kytary Novák` → `K. N.` |

### Navn og tiltaleform

To filtre arbeider med tsjekkiske navn: `vocative` lager tiltaleformen i tsjekkisk vokativ, og `gender` velger en tekst for en mann eller for en kvinne ut fra navnet. De følger de samme reglene som variablene `<first_name_vokativ>` og `<last_name_vokativ>` – hvordan vokativen lages, er beskrevet i [Tsjekkisk vokativ](https://www.bulkgate.com/no/hjelpesenter/verktoy/tsjekkisk-vokativ/).

| skrivemåte | hva filteret gjør | eksempel |
|:--|:--|:--|
| `<first_name\|vocative>` | setter hvert ord i verdien i vokativ | `Petr Novák` → `Petře Nováku` |
| `<first_name\|gender:Milý,Milá>` | setter inn den første teksten for et mannsnavn og den andre for et kvinnenavn – selve verdien settes ikke inn | `Jana` → `Milá` |

- **Vokativ fra hvilken som helst variabel.** I motsetning til `<first_name_vokativ>` kan filteret `vocative` brukes på hvilken som helst variabel – for eksempel på et fullt navn som er lagret i ett felt, eller på en verdi du sender i API-et.
- **Kjønn og type navn** gjenkjenner filteret `vocative` selv ut fra endelsen. Når det tar feil, angir du dem med parametere: den første er `man` eller `woman`, den andre `first` (fornavn) eller `last` (etternavn), for eksempel `<last_name|vocative:woman,last>`. Standardverdien for begge parameterne, `auto`, overlater avgjørelsen til filteret.
- **Store og små bokstaver.** Hvert ord i vokativ begynner med stor bokstav, og de andre bokstavene er små: `NOVÁK` → `Nováku`.
- **Også standardverdien bøyes**, så du skriver den i nominativ: en mottaker uten navn får `Zákazníku` fra `<first_name:zákazník|vocative>`.
- **Kjønnsteksten erstatter verdien**, så skriv variabelen inn i teksten to ganger: `<first_name|gender:Milý,Milá> <first_name|vocative>` gir `Milý Petře` eller `Milá Jano`. Teksten kan også bare være slutten av et ord: `Vážen<first_name|gender:ý pane,á paní>` gir `Vážený pane` eller `Vážená paní`. Begge tekstene er obligatoriske, men kan være tomme; de kan ikke inneholde `<`, `>`, `|` eller komma.
- **Uten navn** avgjøres kjønnet ut fra standardverdien – `<first_name:zákazníku|gender:Milý,Milá>` gir `Milý` til en mottaker uten navn. En tom standardverdi gir alltid teksten for en mann.

> [!WARNING]
> Begge filtrene følger reglene i tsjekkisk, uansett hvor navnet kommer fra. Det engelske navnet John får formen `Johne`. Bruk dem bare i meldinger til tsjekkiske mottakere, og kontroller resultatet for uvanlige navn med en testmelding.

### Lengdebegrensning

Filtre med et tall holder øye med det største antallet tegn verdien kan ha. De er nyttige for lange verdier som et firmanavn eller en adresse, som ellers ville strukket meldingen ut til en ny SMS-del. Filteret bestemmer hva som skjer med en lengre verdi:

| skrivemåte | hva som skjer med en lengre verdi | «Kytary Novák» med en grense på 8 |
|:--|:--|:--|
| `<company_name\|cut:8>` | kortes ned til grensen – ved hele ord der det er mulig | `Kytary` |
| `<company_name\|truncate:8>` | kortes ned og fullføres med `...`, slik at alt til sammen holder seg innenfor grensen | `Kytar...` |
| `<company_name\|ellipsis:8>` | erstattes med `(...)` | `(...)` |
| `<company_name\|empty:8>` | utelates | ingenting |
| `<company_name:firmaet ditt\|fallback:8>` | erstattes med variabelens standardverdi; når den ikke har noen, utelates den | `firmaet ditt` |

En verdi som holder seg innenfor grensen, settes inn i sin helhet.

Med `truncate`, `ellipsis` og `fallback` kan du skrive din egen tekst etter et komma, som brukes i stedet for standardteksten:

| skrivemåte | «Kytary Novák» med en grense på 8 |
|:--|:--|
| `<company_name\|truncate:8,…>` | `Kytary…` |
| `<company_name\|ellipsis:8,firmaet ditt>` | `firmaet ditt` |
| `<company_name\|fallback:8,firmaet ditt>` | `firmaet ditt` |

Din egen tekst kan ikke inneholde `<`, `>`, `|` eller komma. Tom tekst (`truncate:8,`) korter ned verdien uten tillegg.

### Kjeding av filtre

Du kan kombinere filtre fritt – bare skriv dem etter hverandre, hvert etter sin egen loddrette strek. De brukes etter tur fra venstre mot høyre, og hvert filter får resultatet fra det forrige. Slik kan du kombinere en lengdebegrensning med endring av store og små bokstaver og fjerning av mellomrom.

| skrivemåte | kontaktverdi | hva mottakeren får |
|:--|:--|:--|
| `<last_name\|lower\|first_upper>` | `NORDMANN` | `Nordmann` |
| `<city\|trim\|capitalize>` | `"  nedre eiker  "` | `Nedre Eiker` |
| `<company_name\|trim\|truncate:8,…\|upper>` | `"  Kytary Novák "` | `KYTARY…` |
| `<first_name\|word:1\|vocative>` | `Petr Pavel` | `Petře` |

I det tredje eksemplet fjerner `trim` først mellomrommene, `truncate:8,…` korter ned verdien til `Kytary…`, og `upper` gjør den til slutt om til store bokstaver.

- **Rekkefølgen betyr noe.** De samme filtrene i en annen rekkefølge gir et annet resultat. For verdien `"  Ústí nad Labem  "` gir `<city|trim|cut:4>` resultatet `Ústí`, mens `<city|cut:4|trim>` først korter ned verdien til de innledende mellomrommene og deretter fjerner dem – ingenting blir igjen.
- **Standardverdien skrives før filtrene**, og hele kjeden justerer også den: en mottaker uten fornavn får `DER` fra `<first_name:der|trim|upper>`.
- **Hver forekomst av en variabel har sine egne filtre.** Du kan bruke én variabel flere ganger i teksten, hver gang på en annen måte: fra `Hei <first_name|first_upper>, <first_name|upper>` får en mottaker med verdien `ola` teksten `Hei Ola, OLA`.
- **I kampanjeredigeringsprogrammet** følger kjeden rekkefølgen på filtrene i variabeldialogen, og du endrer den ved å dra. Hvert filter kan brukes én gang der.

> [!TIP]
> Sett `trim` foran filtrene som begrenser lengden. Ellers teller også de innledende mellomrommene med i grensen: fra verdien `"  Kytary Novák "` lager `<company_name|cut:8>` bare `"  Kytary"`, mens `<company_name|trim|cut:8>` gir `Kytary`.

### Hva du må passe på

Skriv filternavnet med små bokstaver og uten mellomrom, og tallet bare med sifre.

> [!IMPORTANT]
> Verken et filter eller en grense hindrer at en variabel uten verdi blir stående i teksten. En mottaker du ikke har noen verdi for, får `<company_name>` bokstavelig fra `<company_name|cut:8>`. Hvis du vil ha en reservetekst, skriver du den etter et kolon foran filtrene: `<company_name:firmaet ditt|cut:8>`.

> [!WARNING]
> En skrivefeil i et filter ødelegger variabelen. Et ukjent filter eller et manglende tall – `<first_name|bold>`, `<first_name|cut>` – betyr at skrivemåten slutter å være en variabel og blir stående bokstavelig i teksten, selv for mottakere som har et fornavn. Når variabelen har en standardverdi, blir det feilaktige filteret en del av reserveteksten: `<first_name:der|Upper>` setter inn fornavnet, eller `der|Upper`.

### Utdatert skrivemåte med likhetstegn

Lengden ble tidligere begrenset med en snarvei: grensen ble skrevet etter et likhetstegn, etterfulgt av en bokstav som bestemte hva som skjer med en lengre verdi. **Denne skrivemåten er utdatert** – bruk filtre i nye meldinger. Meldinger som inneholder den, fungerer fortsatt, og kampanjeredigeringsprogrammet skriver den om til et filter.

| utdatert skrivemåte | erstatt med filteret |
|:--|:--|
| `<company_name=8>` eller `<company_name=8c>` | `<company_name\|cut:8>` |
| `<company_name=8t>` | `<company_name\|truncate:8>` |
| `<company_name=8s>` | `<company_name\|ellipsis:8>` |
| `<company_name=8e>` | `<company_name\|empty:8>` |
| `<company_name:firmaet ditt=8d>` | `<company_name:firmaet ditt\|fallback:8>` |

Snarveien brukes som det første filteret, selv når flere filtre følger etter den: `<company_name=8|upper>` er det samme som `<company_name|cut:8|upper>`.

## Variabler i en kampanje

En kampanje henter verdiene fra kontaktene du legger til i den – fra adresseboken, fra en filimport og fra numre som er skrevet inn for hånd.

1. **Legg til mottakerne først.** Variabelmenyen viser bare felt som minst én mottaker i kampanjen har fylt ut. Uten mottakere er den tom.
2. I tekstredigeringsprogrammet klikker du på ikonet `Legg til variabel`, eller du skriver bare `@`. Når du skriver et navn, snevres menyen inn.
3. Velg variabelen. For hver av dem ser du hvor mange prosent av mottakerne som har data for den.

Variabelen vises i teksten som en etikett med feltnavnet, og fargen forteller deg hvordan det står til med dataene:

- **ingen utheving** – alle mottakerne har dataene, eller det er angitt en standardverdi,
- **advarsel** – 30 til 99 % av mottakerne har dataene,
- **feil** – færre enn 30 % av mottakerne har dataene, eller det finnes ikke noe slikt felt.

Klikk på etiketten for å se et sammendrag av variabelen, inkludert de aktive filtrene i den rekkefølgen de brukes, og rediger den derfra:

- **Når verdien mangler** – legg til en reservetekst, la variabelen utelates, eller behold den i teksten.
- **Filtre** – legg dem til ett etter ett fra en meny som er delt inn i store og små bokstaver, tekstjusteringer, navn og tiltaleform samt lengde. For filtre med en parameter fyller du ut et tall eller en tekst, eller du velger et alternativ. Du endrer rekkefølgen ved å dra i håndtaket – filtrene brukes ovenfra og ned – og sletter et filter du ikke trenger. En eksempelverdi viser hva filteret gjør.

Redigeringsprogrammet lagrer variabelen med samme skrivemåte som er beskrevet i [Når verdien mangler](#nar-verdien-mangler) og [Filtre](#filtre), for eksempel `<company_name:firmaet ditt|trim|cut:8>`. En eldre snarvei med likhetstegn skrives samtidig om til et filter.

### Hvilke felt du kan bruke

| variabel | hva den inneholder |
|:--|:--|
| `<first_name>`, `<last_name>` | fornavn og etternavn |
| `<first_name_vokativ>`, `<last_name_vokativ>` | fornavn og etternavn i tsjekkisk vokativ – fylles ut automatisk, se [Tsjekkisk vokativ](https://www.bulkgate.com/no/hjelpesenter/verktoy/tsjekkisk-vokativ/) |
| `<title_before>`, `<title_after>` | tittel foran og etter navnet |
| `<company_name>` | firmanavn |
| `<company_number>`, `<company_vat>` | organisasjonsnummer og MVA-nummer |
| `<email>` | e-post |
| `<url>` | nettadresse |
| `<street1>`, `<street2>`, `<city>`, `<zip>`, `<state>`, `<country>` | adresse – gate, by, postnummer, delstat, land |
| `<phone_mobile>` | telefonnummer |
| `<note>` | merknad |
| `<custom_field_0>` til `<custom_field_9>` | egendefinerte felt |

Når du [importerer fra en fil](https://www.bulkgate.com/no/hjelpesenter/kampanjer/importere-kontakter-via-csv-excel/), knytter du hver kolonne til ett av disse feltene. En kolonne som ingen av dem passer for – et ordrenummer, et rabattbeløp – legges i et egendefinert felt, og i teksten bruker du da for eksempel `<custom_field_0>`.

### Kanaler, lengde og forhåndsvisning

- **Kanaler.** Variabler fungerer i meldingsteksten for SMS, Viber og RCS, og for RCS også i tittelen.
- **Lengde og pris.** Tegntelleren i redigeringsprogrammet regner med verdiene til kontakten som er valgt i forhåndsvisningen. Hver mottaker kan imidlertid ha verdier med ulik lengde – derfor beregnes antallet SMS-deler og prisen for hver mottaker for seg, etter at verdiene er satt inn.
- **Unicode.** Diakritiske tegn fra en innsatt verdi gjør SMS-en om til Unicode bare når du har aktivert det i tekstinnstillingene.
- **Forhåndsvisning.** Både forhåndsvisningen av meldingen og `Send testmelding` setter inn verdiene til kontakten som er valgt i forhåndsvisningen – så du ser hvordan teksten blir før den sendes. Unntaket er filtrene `vocative` og `gender`: forhåndsvisningen i redigeringsprogrammet bøyer ikke navnet, men markerer det bare med 🗣️, og for `gender` viser den begge tekstene, for eksempel `Milý/Milá`. Tegntelleren regner også med disse formene. Det faktiske resultatet ser du i en testmelding.

## Variabler i API-et

I API-et sender du verdiene direkte i forespørselen, i parameteren `variables`: et objekt der nøkkelen er variabelnavnet og verdien er det som skal settes inn. Teksten bruker samme skrivemåte, inkludert standardverdier og [filtre](#filtre).

```json
{
	"number": "420777777777",
	"text": "Hei <first_name:der>, bestilling <order> er på vei.",
	"variables": {"first_name": "Ola", "order": "12345"}
}
```

Mottakeren får `Hei Ola, bestilling 12345 er på vei.` Du kan kalle en variabel hva du vil – `<order>` i eksemplet er ikke et kontaktfelt, bare en nøkkel fra `variables`.

### Hvor variablene hører hjemme

| API | hvor `variables` hører hjemme |
|:--|:--|
| [Advanced API – transaksjonsmeldinger](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-transactional/2.0/) | sammen med hele meldingen; i versjon 2.0 også sammen med hvert nummer i `number` for seg – verdier ved nummeret har forrang |
| [Advanced API – markedsføringsmeldinger](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-promotional/2.0/) | sammen med hvert nummer i `number` for seg; `variables` for hele meldingen brukes ikke |
| [Advanced API – grupper i adresseboken](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-promotional-sende-til-grupper/) | sendes ikke – feltene til kontaktene i adresseboken fylles ut, med de samme navnene som i en [kampanje](#hvilke-felt-du-kan-bruke) |
| [Integration API](https://www.bulkgate.com/no/dokumentasjon/integration-api/integration-transactional/) | sammen med hver melding |

### Hvilke verdier du skal sende

- **Tekst eller et tall.** Tall settes inn som de er (`12` → `12`).
- **`null`, `false` og tom tekst** regnes som en manglende verdi – da gjelder [standardverdien](#nar-verdien-mangler), ellers blir variabelen stående bokstavelig i teksten.
- **En matrise eller et objekt som verdi** godtas ikke av Advanced API, som returnerer feilen `invalid_input_parameters`.
- **Ekstra nøkler** som ikke finnes i teksten, ignoreres.
- **Vokativ.** Ut fra `first_name` og `last_name` beregner Advanced API selv `first_name_vokativ` og `last_name_vokativ` – egne verdier for disse to nøklene overskrives. Integration API beregner ikke vokativ. Hvordan det fungerer, er beskrevet i [Tsjekkisk vokativ](https://www.bulkgate.com/no/hjelpesenter/verktoy/tsjekkisk-vokativ/).

### Kanaler og lengde

| kanal | hvor variablene settes inn |
|:--|:--|
| SMS | tekst |
| Viber | tekst, knappetekst og lenke |
| RCS | tekst, korttittel og beskrivelse |
| Tale | tekst |

Antallet SMS-deler og prisen beregnes begge ut fra teksten etter at verdiene er satt inn. Diakritiske tegn fra en innsatt verdi gjør SMS-en om til Unicode bare med `"unicode": true`. Tekst i Viber, RCS og WhatsApp som etter innsettingen av verdiene blir lengre enn grensen for kanalen (Viber 1 000 tegn, RCS og WhatsApp 5 000), kortes ned.

> [!NOTE]
> Programtillegg for nettbutikker har sitt eget sett med variabler, for eksempel `<customer_firstname>`. De er beskrevet i [SMS til kunder](https://www.bulkgate.com/no/hjelpesenter/integrasjoner/nettbutikkmoduler/sms-til-kunder/).