GMS API-compatibiliteit

SMSBAT ondersteunt een compatibiliteitslaag met de GMS API. Hierdoor kunt u uw bestaande integraties die zijn ontworpen voor GMS rechtstreeks naar SMSBAT migreren zonder dat u uw berichtrouteringsschema's, payload-structuren of callback-listeners hoeft te wijzigen.

Verbindingsinstellingen

Om verzoeken via SMSBAT te routeren, updatet u de basis-URL en authenticatiegegevens in uw integratie:

Basis-URL: https://restapi.smsbat.com
Eindpunt: POST /api/GMSMessage/send_message
Verzoekformaat: application/json
Authenticatie: HTTP-basisauthenticatie (gebruikt uw SMSBAT API-inloggegevens)

Verzoekparameters

De GMS-compatibiliteits-API accepteert een JSON-object met de volgende parameters op het hoogste niveau:

Parameter	Typ	Vereist	Beschrijving
`telefoonnummer`	tekenreeks	Ja	Telefoonnummer van de ontvanger in internationaal formaat (bijvoorbeeld '380501234567').
`label`	tekenreeks	Ja	Geregistreerde afzendernaam/alfanaam.
`kanalen`	array	Ja	Lijst met kanalen die u kunt proberen, in volgorde van prioriteit. Ondersteunde waarden: `viber`, `sms`, `push`. Bijvoorbeeld `["viber", "sms"]`.
`kanaalopties`	voorwerp	Ja	Kaart met opties voor elk actief kanaal (zie hieronder).
`extra_id`	tekenreeks	Nee	Uw interne bericht-ID aan de klantzijde.
`callback_url`	tekenreeks	Nee	Eindpunt-URL op uw systeem om callbacks voor de leveringsstatus te ontvangen.
`divisie_code`	tekenreeks	Nee	Optionele divisiecode-ID (standaard ingesteld op 'hoofd').

Instellingen kanaalopties

Het object channel_options bevat kanaalspecifieke configuraties.

Viber-berichtViber met SMS-terugvalSMS-berichtViber-enquêteViber-carrouselPushbericht

Wordt gebruikt wanneer viber wordt vermeld in de channels-array.

Parameter	Typ	Vereist	Beschrijving
`tekst`	tekenreeks	Ja	Hoofdtekst van bericht.
`ttl`	geheel getal	Ja	Time-To-Live in seconden.
`img`	tekenreeks	Nee	Openbare HTTPS-URL van de afbeelding die moet worden weergegeven.
`onderschrift`	tekenreeks	Nee	Knop tekstlabel.
`actie`	tekenreeks	Nee	Bestemmings-URL wanneer op de knop wordt geklikt.
`enquête_opties`	array	Nee	Array van tekenreeksen (2 tot 5 items) die als onderzoeksopties moeten worden weergegeven.
`carrousel_items`	array	Nee	Array van dia-objecten om weer te geven als een Viber-carrousel (zie structuur op tabblad).

Viber-verzoekvoorbeeld:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Maakt Viber-berichten mogelijk met een automatische SMS-fallback als Viber-bezorging binnen de TTL mislukt.

Voorbeeld van een terugvalverzoek:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Wordt gebruikt wanneer sms wordt vermeld in de channels-array.

Parameter	Typ	Vereist	Beschrijving
`tekst`	tekenreeks	Ja	Hoofdtekst van bericht.
`alfa_naam`	tekenreeks	Ja	Alfanaam van afzender.
`ttl`	geheel getal	Ja	Time-To-Live in seconden.
`ctr`	booleaans	Nee	Schakel het bijhouden van CTR-klikken in voor links in tekst (`true`/`false`).

** Voorbeeld van sms-verzoek: **

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Wordt gebruikt om Viber-peilingen en enquêtes te maken.

Waarschuwing

De Viber-enquêteconfiguratie moet tussen 2 en 5 opties binnen survey_options bevatten.

Voorbeeld van enquêteverzoek:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Wordt gebruikt om veegbare diakaarten met afbeeldingen te verzenden. Elke dia ondersteunt afbeeldingen, titels en knoppen.

Voorbeeld carrouselverzoek:

href="#__codelineno-4-1">{ "phone_number": "380501234567", "tag": "MySender", "channels": ["viber"], "channel_options": { "viber": { "text": "Choose an offer", "ttl": 60, "carousel_items": [ { "title": "Offer 1", "image_url": "https://www.example.com/offer-1.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-1", "secondary_label": "More", "secondary_url": "https://www.example.com/offers" }, { "title": "Offer 2", "image_url": "https://www.example.com/offer-2.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-2" } ] } } }

Wordt gebruikt wanneer push wordt vermeld in de channels-array.

Parameter	Typ	Vereist	Beschrijving
`titel`	tekenreeks	Ja	Titeltekst van de pushmelding.
`tekst`	tekenreeks	Ja	Hoofdtekst van bericht.
`ttl`	geheel getal	Ja	Time-To-Live in seconden.
`img`	tekenreeks	Nee	Openbare HTTPS-URL van de afbeelding die moet worden weergegeven.
`onderschrift`	tekenreeks	Nee	Knop tekstlabel.
`actie`	tekenreeks	Nee	Bestemmings-URL wanneer op de knop wordt geklikt.
`ctr`	booleaans	Nee	Kliktracking inschakelen.

** Voorbeeld van een pushverzoek: **

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Antwoordformaat

Het eindpunt retourneert antwoorden in JSON-indeling met de statuscode 'HTTP 200 OK'.

Succesvolle reactie

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Foutreacties

Als de validatie of verwerking mislukt, wordt een foutreactie met een niet-null ErrorCode en gedetailleerde ErrorText geretourneerd.

Niet-ondersteund kanaal/optieOngeldig aantal enquêteoptiesNiet-geregistreerde alfanaamInterne verwerkingsfout

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Terugbelleveringsformaat

Als callback_url in de aanvraag is opgegeven, verzendt SMSBAT updates van de leveringsstatus als een JSON POST-payload naar uw eindpunt.

Voorbeeld van terugbelverzoek

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Terugbelvelden Beschrijving

Veld	Typ	Beschrijving
`nummer`	tekenreeks	Telefoonnummer van de ontvanger.
`tijd`	nummer	Tijdstempel van gebeurtenis in Unix-milliseconden.
`status`	nummer	Vereenvoudigde statusidentificatie (zie Statuscodetabel).
`substatus`	nummer	Gedetailleerde statusidentificatie (zie tabel Substatuscodes).
`hyber_status`	nummer	Gedetailleerde SMSBAT interne statuscode (zie Hyberstatustabel).
`bericht_id`	tekenreeks	SMSBAT-bericht-ID (GUID) gegenereerd bij verzending.
`extra_id`	tekenreeks	ID aan de klantzijde verstrekt in het oorspronkelijke verzoek.
`verzonden_via`	tekenreeks	Kanaal dat het bericht heeft verwerkt: `viber`, `sms` of `rcs`.
`matching_template_id`	nummer	Overeenkomststatus van Viber-sjabloon (indien van toepassing).

Statustoewijzingen

1. Vereenvoudigde status (`status`)

Code	Betekenis
`1`	Bericht geaccepteerd of afgeleverd.
`2`	Bericht afgeleverd.
`3`	Verwerkings- of leveringsfout.

2. Gedetailleerde status (`substatus`)

Code	Betekenis
`12`	Geaccepteerd voor verwerking.
`23`	Afgeleverd.
`24`	Gezien/gelezen.
`35`	Niet geleverd binnen TTL (verlopen).
`36`	Leveringsfout.

3. Kanaaltype (`sent_via`)

Kanaal	Beschrijving
`viber`	Status geproduceerd door Viber-kanaal.
`sms`	Status geproduceerd door SMS-kanaal.
`rcs`	Status geproduceerd door RCS-kanaal.

4. Gedetailleerde SMSBAT-status (`hyber_status`)

Code	Kanaal	Staat	Substatus	Betekenis
23033	`viber`	`2`	`23`	Viber-bericht afgeleverd.
24013	`viber`	`2`	`24`	Viber-bericht gelezen door ontvanger (gezien).
36013	`viber`	`3`	`36`	Interne fout in Viber.
36023	`viber`	`3`	`36`	Ongeldige of niet-beschikbare Viber-service-ID.
36033	`viber`	`3`	`36`	Ongeldige Viber-payloadgegevens.
36037	`viber`	`3`	`36`	Viber-afbeeldings-URL te lang.
36038	`viber`	`3`	`36`	Ongeldige Viber-afbeeldings-URL.
36039	`viber`	`3`	`36`	Viber-tekst te lang.
36044	`viber`	`3`	`36`	Lege Viber-tekst.
36053	`viber`	`3`	`36`	Niet-ondersteund Viber-berichttype.
36063	`viber`	`3`	`36`	Ongeldige Viber-parameters.
36073	`viber`	`3`	`36`	Time-out van Viber-provider.
36083	`viber`	`3`	`36`	Viber-afzender geblokkeerd door de ontvanger.
36093	`viber`	`3`	`36`	Ontvanger is niet geregistreerd als Viber-gebruiker.
36103	`viber`	`3`	`36`	Geen Android/iOS-apparaat met Viber-ondersteuning gevonden.
36113	`viber`	`3`	`36`	Ongeautoriseerd IP-adres voor verzending via Viber.
36123	`viber`	`3`	`36`	Dubbel Viber-bericht gedetecteerd.
36143	`viber`	`3`	`36`	Factureringsfout in Viber.
36153	`viber`	`3`	`36`	Bericht geblokkeerd door zwarte lijst van platform.
36163	`viber`	`3`	`36`	Interne verwerkingsfout in Viber-platform.
36173	`viber`	`3`	`36`	Verkeerd of ontbrekend Viber-label.
36183	`viber`	`3`	`36`	Ongeldige Viber TTL-waarde.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS geaccepteerd.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS onderweg.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS afgeleverd.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS verlopen (niet afgeleverd binnen TTL).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS-bericht verwijderd.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS kan niet worden afgeleverd.
36041	`sms` / `rcs`	`3`	`36`	Onbekende SMS/RCS-bezorgstatus.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS-bericht afgewezen.