## API-URL
URL som brukes til å sende HTTP-forespørsler:
```url
https://portal.bulkgate.com/api/2.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/2.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 | - |
| channel | Alternative kanaler. Kanalene prøves i en kaskade, i den rekkefølgen du oppgir dem i objektet - hvis vi ikke klarer å levere meldingen gjennom den første kanalen, brukes den neste i listen. SMS legges **ikke** til automatisk; hvis du vil ha SMS som siste reserve, må du ta med objektet `sms` i kaskaden. Hvis ingen kanal er angitt i det hele tatt, sendes meldingen som SMS. | Nei | [SMS-objekt](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-sms/) |
| 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) (`777777777` + `CZ` = `420777777777`). 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
[
"420777777777",
"420888888888",
"420999999999"
]
```
- 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": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
]
```
Variabler fra listen `variables` kan settes inn i malen i parameteren `text`.
## 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 – markedsføring](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-viber-markedsforing/) |
| `rcs` | [RCS](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-rcs/) |
| `whatsapp` | [WhatsApp](https://www.bulkgate.com/no/dokumentasjon/advanced-api/advanced-whatsapp/) |
## Eksempler på forespørsler
**Eksempel på fullstendig forespørsel:**
```http-json
POST /api/2.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": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
],
"groups": [1, 2],
"admins": [1, 4],
"text": "RCS: Fremtidens mobilmeldinger for bedrifter",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00",
"channel": {
"whatsapp": {
"sender": "420777777777",
"expiration": 300,
"message": {
"text": "text"
}
},
"rcs": {
"sender": "BulkGate",
"expiration": 300,
"message": {
"text": "text"
}
},
"viber": {
"sender": "Lt. Hagan",
"expiration": 100,
"button": {
"caption": "Gå til BulkGate",
"url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/"
},
"image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg",
"text": "*RCS: Fremtidens mobilmeldinger for bedrifter*\n\nHar du noen gang ønsket at du kunne sende mer enn bare tekst i en SMS, for eksempel et bilde i høy oppløsning eller en interaktiv knapp? Eller ønsket du deg en lesebekreftelse, bare for å vite at meldingen kom frem? Rich Communication Services (RCS) er her for å revolusjonere måten bedrifter kommuniserer på, forbedre meldingsopplevelsen og overvinne disse begrensningene."
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "RCS: Fremtidens mobilmeldinger for bedrifter"
}
}
}
```
**Eksempel på en forespørsel der mottakerne angis som en liste over numre og sendetidspunktet planlegges som Unix-tidsstempel:**
```http-json
POST /api/2.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": [
"420777777777",
"420888888888",
"420999999999"
],
"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":"420777777777",
"channel":"sms"
},
{
"status":"scheduled",
"sms_id":"idyrcmdd-1",
"part_id":[
"idyrcmdd-1_1",
"idyrcmdd-1"
],
"number":"420888888888",
"channel":"sms"
},
{
"status":"invalid_number",
"code":400,
"error":"Invalid phone number",
"detail":null,
"number":"420999999999",
"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/).