## API-URL
URL som brukes til å sende HTTP-forespørsler:
```url
https://portal.bulkgate.com/api/1.0/advanced/promotional
```
> [!NOTE]
> Hvis forespørselen ikke kommer frem, kan du sende den på nytt til [reserveserveren](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-reserveserver/) `backup1.bulkgate.com`.
## Støttede HTTP-metoder
- `POST` - `application/json`
```http
POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```
## Parametertabell
| PARAMETERNAVN | VERDI | OBLIGATORISK | STANDARDVERDI |
|:------------------|:------|:------------:|:-------------:|
| application_id | [Application ID](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/administrasjon-av-api/) | **Ja** | - |
| application_token | [Application token](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-token/) | **Ja** | - |
| number | Liste over mottakere - [Verdi number](#verdi-number) | **Ja** eller `admins` eller `groups` | - |
| groups | Liste over numrene til grupper i BulkGate-adresseboken. [Mer informasjon](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-promotional-sende-til-grupper/) | **Ja** eller `number` eller `admins` | - |
| admins | Liste over numrene til BulkGate-administratorer som mottar varsler. [Mer informasjon](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-promotional-meldinger-til-administratorer/) | **Ja** eller `number` eller `groups` | - |
| text | Teksten i SMS-meldingen (maks. 612 tegn, eller 268 tegn hvis Unicode er aktivert), UTF-8-koding | **Ja**, hvis `number` er angitt som en liste over numre, eller hvis parameteren `groups` eller `admin` brukes | - |
| unicode | `Yes`/`true`/`1` for Unicode-SMS, no/false/0 for 7-biters SMS | Nei | `false` |
| sender_id | Avsender-ID, se [Avsendertype](#avsendertype-sender-id) | Nei | `gSystem` |
| sender_id_value | Avsenderverdi - `gOwn` (f.eks. "420 777 777 777"), `gText` (f.eks. "BulkGate"), `gProfile` (f.eks. "423"), `gMobile` eller `gPush` [(KEY)](https://www.bulkgate.com/no/hjelpesenter/mobile-connect/mobile-connect-installasjon/) | Nei | `null` |
| country | Oppgi mottakernumrene i internasjonalt format (med landsprefiks, f.eks. `420`), eller legg til en [landskode](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Se eksemplet på bruk av land. Hvis verdien er **`null`**, brukes tidssonen du har stilt inn, til å fylle ut informasjonen | Nei | `null` |
| schedule | Planlegg dato og klokkeslett for sending som [Unix-tidsstempel](https://en.wikipedia.org/wiki/Unix_time) eller i [ISO 8601-format.](https://en.wikipedia.org/wiki/ISO_8601) Se eksemplene nedenfor | Nei | Nå |
| duplicates_check | Velg **`same_text`** for å hindre at like meldinger sendes til samme telefonnummer. Med **`same_number`** hindrer du at det sendes en melding med samme eller annen tekst til samme nummer. Ved **`null`** fjernes ingen duplikater. Duplikater fjernes **bare innenfor én og samme sending**, ikke på tvers av forespørsler. | Nei | `null` |
| tag | Etikett på meldingen som brukeren senere kan søke etter den med. | Nei | - |
### Verdi `number`
Verdien number kan skrives på to måter:
- Liste over telefonnumre
```json
[
"420775123456",
"420606123456",
"44771447678"
]
```
- Assosiativ liste med strukturen `number`, `text` og `variables`, der den eneste obligatoriske parameteren er `number`. Hvis `number` ikke er fylt ut, hoppes meldingen over.
```json
[
{"number": "420775123456", "text": "test1 ", "variables": {"a": 5}},
{"number": "420606123456", "text": "test2 ", "variables": {"b": 5}},
{"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
]
```
Variabler fra listen `variables` kan settes inn i malen i parameteren `text`.
### Avsendertype `sender_id`
| VERDI | BETYDNING |
|:-----------|:---------------------------------------------------------------------|
| `gSystem` | Systemnummer |
| `gShort` | Kortnummer |
| `gText` | Tekstavsender |
| `gMobile` | [Mobile Connect](https://www.bulkgate.com/no/hjelpesenter/mobile-connect/mobile-connect-installasjon/) |
| `gPush` | Mobile Connect push - sender et varsel til Mobile Connect-appen |
| `gOwn` | Eget nummer (krever verifisering av nummeret) |
| `gProfile` | [BulkGate-profil-ID](https://www.bulkgate.com/no/hjelpesenter/sms/avsenderprofil/) |
| `` | BulkGate-profil-ID |
## Eksempler på forespørsler
**Eksempel på fullstendig forespørsel:**
```http-json
POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
{"number": "420775123456", "text": "test1 ", "variables": {"a": 5}},
{"number": "420606123456", "text": "test2 ", "variables": {"b": 5}},
{"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
],
"unicode": true,
"groups": [1, 2],
"admins": [1, 4],
"text": "Hello, ",
"sender_id": "gText",
"sender_id_value": "BulkGate",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00"
}
```
**Eksempel på en forespørsel der mottakerne angis som en liste over numre og sendetidspunktet planlegges som Unix-tidsstempel:**
```http-json
POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
"420775123456",
"420606123456",
"44771447678"
],
"text": "Hello, ",
"schedule": "1526992636"
}
```
## Svar
**Ved suksess:**
```json
{
"data": {
"total": {
"status": {
"sent": 0,
"accepted": 0,
"scheduled": 2,
"error": 0,
"blacklisted": 0,
"invalid_number": 1,
"invalid_sender": 0
}
},
"response": [
{
"status": "scheduled",
"sms_id": "idyrcmdd-0",
"part_id": [
"idyrcmdd-0_1",
"idyrcmdd-0"
],
"number": "420775123456",
"channel": "sms"
},
{
"status": "scheduled",
"sms_id": "idyrcmdd-1",
"part_id": [
"idyrcmdd-1_1",
"idyrcmdd-1"
],
"number": "420606123456",
"channel": "sms"
},
{
"status": "invalid_number",
"code": 400,
"error": "Invalid phone number",
"detail": null,
"number": "44771447678",
"channel": "sms"
}
]
}
}
```
Der:
- **part_ID** er en liste over 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 finner du [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 feiltypene for Simple API og Advanced API [her](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-feiltyper/).