> [!CAUTION]
> Det er **strengt forbudt** å bruke [transaksjons-SMS](https://www.bulkgate.com/no/hjelpesenter/generell-informasjon/forskjellen-mellom-markedsforings-og-transaksjonsmeldinger/) til promotering eller markedsføring. Den skal kun brukes til varsling – som et SMS-varsel.

> [!NOTE]
> Hvis du vil bruke en transaksjonsrute til å sende et masseutsendt varsel, kan du kontakte [kundestøtten vår](https://www.bulkgate.com/no/kontakt-oss/). Vi kan tillate dette dersom det er god grunn til det.

## API-URL

URL for sending av HTTP-forespørsler:

```url
https://portal.bulkgate.com/api/2.0/advanced/transactional
```

> [!NOTE]
> Hvis forespørselen ikke når frem, gjentar du den på [reserveserveren](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-reserveserver/) `backup1.bulkgate.com`.

## Støttede HTTP-metoder

- `POST` - `application/json`

```http
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

## Parametertabell

| PARAMETERNAVN     | VERDI | OBLIGATORISK | STANDARDVERDI |
|:------------------|:------|:------------------------------:|:------------------------------------------:|
| application_id    | [Applikasjonsidentifikator](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/administrasjon-av-api/) | **Ja** | - | 
| application_token | [Autentiseringstoken for applikasjonen](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-token/) | **Ja** | - |
| number            | Mottakerens nummer eller en matrise med mottakernumre – [Verdi number](#verdi-number) | **Ja** eller `admin` | - |
| admin             | Nummeret til BulkGate-administratoren som mottar varselet. [Mer informasjon](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-transactional-meldinger-til-administratorer/) | **Ja** eller `number` | - |
| text              | Teksten i SMS-meldingen (maks. 612 tegn, eller 268 tegn hvis Unicode brukes), UTF-8-koding. Du kan legge til variabler i malen fra matrisen `variables` (en annen parameter) `Hei <first_name> <last_name> ....` | **Ja** | - |
| variables         | Assosiativ matrise for å legge variabler til i teksten, f.eks.: `{"first_name": "Ola", "last_name": "Nordmann"}` | Nei | `[]` |
| channel           | Alternative kanaler. Kanalene prøves i en kaskade, i den rekkefølgen du oppgir dem i objektet – hvis vi ikke klarer å levere meldingen via den første kanalen, brukes den neste i listen. SMS legges **ikke** til automatisk; vil du ha den som siste reserve, tar du med objektet `sms` i kaskaden. Hvis ingen kanal er oppgitt i det hele tatt, sendes meldingen som SMS. | Nei | [SMS-objekt](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-sms/) |
| country           | Oppgi mottakernes numre i internasjonalt format (med landsprefiks, f.eks. `420`), eller legg til [landskoden i formatet ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Se eksempelforespørselen med land. Hvis verdien er **`null`**, brukes tidssonen du har angitt, til å fylle ut informasjonen | Nei | `null` |
| schedule          | Planlegg dato og klokkeslett for sendingen i [Unix-tidsstempel](https://en.wikipedia.org/wiki/Unix_time) eller [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Nei | Nå |
| duplicates_check  | Velg **`on`** for å hindre at duplikatmeldinger sendes til samme telefonnummer. Meldinger med samme tekst sendt til samme nummer fjernes hvis tidsintervallet mellom dem er kortere enn 5 minutter. Med **`off`** fjernes ingen duplikater. | Nei | `off` |
| tag               | Meldingsetikett som brukeren senere kan hente meldingene etter. | Nei | - |

### Verdi `number`

Verdien number kan skrives slik:

- Matrise med telefonnumre

```json
[
	"420777777777",
	"420888888888", 
	"420999999999"
]
```

## Kanaler

Objektet `channel` bestemmer hvilke kanaler meldingen sendes gjennom, og i hvilken rekkefølge. **Rekkefølgen på nøklene i forespørselen er rekkefølgen i kaskaden**, og SMS legges ikke til automatisk – se [Kanalkaskade](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-kaskade/).

| NØKKEL       | KANALOBJEKT                                                    |
|:-------------|:---------------------------------------------------------------|
| `sms`        | [SMS](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-sms/)                                  |
| `viber`      | [Viber – transaksjoner](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-viber-transaksjoner/) |
| `rcs`        | [RCS](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-rcs/)                                  |
| `whatsapp`   | [WhatsApp](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-whatsapp/)                        |

## Eksempel på forespørsel

```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", 
	"number": ["777777777", "777777778"], 
	"text": "example text <first_name>",
	"variables": {"first_name": "John"},
	"country": "cz",
	"schedule": "2023-08-14T18:30:00-01:00",
	"channel": {
		"whatsapp": {
			"sender": "420777777777",
			"expiration": 300,
			"message": {
				"text": "text"
			}
		},
		"rcs": {
			"sender": "BulkGate",
			"expiration": 300,
			"message": {
				"text": "text"
			}
		},
		"viber": {
			"sender": "BulkGate",
			"expiration": 100
		},
		"sms": {
			"sender_id": "gText",
			"sender_id_value": "Mr. Sender",
			"unicode": true
		}
	}
}
```

## Svar

**Ved suksess:**

```json
{
    "data": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 2,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0,
                "duplicity_message": 0
            }
        },
        "response": [
            {
                "status": "scheduled",
                "message_id": "transactional-64afe5f28ffc2-0",
                "part_id": [
                    "transactional-64afe5f28ffc2-0"
                ],
                "number": "420777777777",
                "channel": "viber"
            },
            {
                "status": "scheduled",
                "message_id": "transactional-64afe5f28ffc2-1",
                "part_id": [
                    "transactional-64afe5f28ffc2-1"
                ],
                "number": "420777777778",
                "channel": "viber"
            }
        ]
    }
}
```

Der:

- **part_ID** er en matrise med ID-ene til delene av den opprinnelige lange meldingen, som ble delt opp fordi den overskred grensen på 160 tegn for én melding. Mer informasjon [her](https://www.bulkgate.com/no/hjelpesenter/sms/sammenkjedede-meldinger/).

**Ved feil:**

```json
{
    "type": "invalid_phone_number",
    "code": 400,
    "error": "Invalid phone number",
    "detail": null
}
```

```json
{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "detail": null
}
```

Der:

- **type** og **error** (beskrivelse av feilen) finner du i [tabellen over feiltyper](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-feiltyper/) 
- **code** er HTTP-feilkoden
- **detail** er tilleggsinformasjon om feilen

Se alle feiltyper for Simple API og Advanced API [her](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-feiltyper/).