## API-URL
URL for sending av HTTP-forespørsler:
```url
https://portal.bulkgate.com/api/1.0/integration/promotional
```

> [!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`.

```http
POST /api/1.0/integration/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

### Parametertabell

| PARAMETERNAVN     | VERDI | OBLIGATORISK | STANDARDVERDI |
|:------------------|:------|:---------:|:---------------------------------:|
| application_id    | [Applikasjons-ID](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** | - |
| tag               | Egen identifikasjonsetikett | Nei | - |
| messages          | Matrise med meldinger | **Ja** | [Meldingsobjekt](#meldingsobjekt) |


### Meldingsobjekt

| PARAMETERNAVN   | VERDI | OBLIGATORISK | STANDARDVERDI |
|:----------------|:------|:---------:|:---------------------------------------:|
| primary_channel | Primærkanalen som brukes først i kaskaden | Nei | `sms` |
| phone_number    | Mottakerens telefonnummer | **Ja** | - |
| country         | Oppgi mottakernumrene i internasjonalt format (med landsprefiks, f.eks. `420`), eller legg til [landskode](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Se eksempelet med krav om 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). Se eksemplene nedenfor | Nei | `null` |
| channels        | Assosiativ matrise med kanalobjekter | **Ja** | [Kanalobjekt](#viber-kanalobjekt) |


### Viber-kanalobjekt

| PARAMETERNAVN  | VERDI | OBLIGATORISK | STANDARDVERDI |
|:---------------|:------|:---------:|:-------------:|
| sender         | Avsendernavn | Nei | - |
| expiration     | Tiden før meldingen utløper | Nei | `3600` |
| button_caption | Knappetekst | Nei | `OK` | 
| button_url     | Knappens URL | Nei | `#` |
| image          | URL til bildet i meldingen | Nei | `null` |
| image_zoom     | Kan bildet forstørres? | Nei | `false` |
| text           | Meldingstekst. 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 | `[]` |

### SMS-kanalobjekt
| PARAMETERNAVN   | VERDI | OBLIGATORISK | STANDARDVERDI |
|:----------------|:------|:---------:|:-------------:|
| 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` [(NØKKEL)](https://www.bulkgate.com/no/hjelpesenter/mobile-connect/mobile-connect-installasjon/) | Nei | `''` |
| unicode         | `Yes`/`true`/`1` for Unicode-SMS, `no`/`false`/`0` for 7-bits SMS | Nei | `false` | 
| text            | SMS-tekst (maks. 612 tegn, eller 268 tegn hvis Unicode er aktivert), UTF-8-koding. Du kan legge til variabler i malen fra matrisen `variables` (en ekstra 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 | `[]` |

#### Avsendertype `sender_id`

| VERDI      | BESKRIVELSE                                                           |
|:-----------|:----------------------------------------------------------------------|
| `gSystem`  | Systemnummer                                                          | 
| `gShort`   | Kortnummer (Short Code)                                               | 
| `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 din   |
| `gOwn`     | Eget nummer (krever bekreftelse av nummeret)                          |
| `gProfile` | [Avsenderprofil-ID](https://www.bulkgate.com/no/hjelpesenter/sms/avsenderprofil/)                            |
| `<int>`    | Avsenderprofil-ID                                                     | 



**Eksempel på fullstendig forespørsel:**
```http-json
POST /api/1.0/integration/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "tag": "",
  "messages": [
    {
      "primary_channel": "sms",
      "phone_number": "420777777777",
      "country": "cz",
      "channels": {
        "viber": {
          "sender": "BulkGate",
          "expiration": 3600,
          "button_caption": "OK",
          "button_url": "#",
          "image": "",
          "image_zoom": false,
          "text": "test <variable_1>",
          "variables": {
            "variable_1": "name"
          }
        },
        "sms": {
          "sender_id": "gSystem",
          "sender_id_value": "BulkGate",
          "unicode": false,
          "text": "test <variable_1>",
          "variables": {
            "variable_1": "name"
          }
        }
      }
    },
    {
      "primary_channel": "sms",
      "phone_number": "420777777778",
      "country": "cz",
      "channels": {
        "viber": {
          "sender": "BulkGate",
          "expiration": 3600,
          "button_caption": "OK",
          "button_url": "#",
          "image": "",
          "image_zoom": false,
          "text": "test <variable_1>",
          "variables": {
            "variable_1": "name"
          }
        },
        "sms": {
          "sender_id": "gSystem",
          "sender_id_value": "BulkGate",
          "unicode": false,
          "text": "test <variable_1>",
          "variables": {
            "variable_1": "name"
          }
        }
      }
    }
  ]
}
```


## Svaret på denne kommandoen kan være:

**Ved suksess**
```json
{
    "data": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 2,
                "scheduled": 0,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0
            }
        },
        "response": [
            {
                "status": "accepted",
                "message_id": "############-0",
                "part_id": [
                    "############-0"
                ],
                "number": "420777777777",
                "channel": "sms"
            },
            {
                "status": "accepted",
                "message_id": "############-1",
                "part_id": [
                    "############-1"
                ],
                "number": "420777777778",
                "channel": "sms"
            }
        ]
    }
}
```

**Ved feil:**
```json
{
    "data": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 0,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0
            }
        },
        "response": []
    }
}
```

```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

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