Vóór het verzenden
Verzend een SMS of ondersteunde MMS met een verzendnummer dat voor uw account is ingesteld. Dit is een handeling in de productieomgeving die ontvangers kan bereiken en kosten kan veroorzaken. Verzend alleen naar ontvangers waarvoor u toestemming hebt en gebruik uitsluitend goedgekeurd berichtenverkeer; de onderstaande voorbeeldnummers en referentie zijn fictief.
Uw account moet zijn goedgekeurd voor uitgaand berichtenverkeer en beschikken over de toepasselijke machtigingen voor afzenders, landen en berichtenverkeer. Rechtstreekse inloggegevens van persoonlijke gebruikers/consumenten komen niet in aanmerking voor deze API. Voor goedgekeurde, specifiek voor de API bestemde inloggegevens geldt een afzonderlijk toelatingstraject; voor mobiele P2P-afzenders kunnen aanvullende machtigingen voor P2P en de VS/Canada vereist zijn. Stem de juiste accountconfiguratie af met MultiTEL en beschouw API-inloggegevens niet als automatische toestemming om elk soort berichtenverkeer te verzenden.
Verzendaanvraag
Verifieer uw identiteit via HTTPS met een ingeschakeld API-account vanaf het daarvoor toegestane bron-IP-adres. Bewaar inloggegevens in een opslag voor geheimen aan de serverzijde. Gebruik POST met formuliergecodeerde velden, of een JSON-object als er geen formulier- of queryvelden worden meegegeven. Plaats geen inloggegevens of berichttekst in een URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Veld | Verplicht | Betekenis |
|---|---|---|
| from | Ja | Uw ingestelde verzendnummer, bij voorkeur als volledige internationale cijferreeks. |
| to | Ja | Eén bestemming, door komma's gescheiden bestemmingen of een JSON-array. Gebruik bij voorkeur volledige internationale cijferreeksen. Een groepsaanvraag kan worden afgewezen vanwege de toepasselijke P2P- of landenlimieten; dit is geen API voor onbeperkte bulkverzending. |
| text | Voor SMS | Berichttekst in UTF-8. Er moet ten minste niet-lege tekst of media worden opgegeven. Verstuur daadwerkelijke tekens en regeleinden in plaats van HTML of procentgecodeerde tekst. Sommige verwerkingspaden via providers normaliseren letterlijke escape-tekenreeksen. |
| media | Voor MMS met alleen media | Base64-gecodeerde media-inhoud, geen URL of bestandspad. De beschikbaarheid, indeling en grootte van MMS zijn afhankelijk van de ingestelde route. Vraag bij MultiTEL na welke media worden ondersteund; deze verwerkingsroutine legt geen universele limiet voor de mediagrootte vast. |
| reference | Aanbevolen | Uw correlatielabel, dat in registraties en callbacks wordt bewaard. Geef er een mee om problemen te kunnen onderzoeken. Het is geen idempotentiesleutel. |
| notifyurl | Nee | Uw HTTPS-ontvanger voor callbacks. De verwerkingsroutine kan na verwerking een eerste resultaat via POST versturen. U moet deze ontvanger zelf beheren en het mag geen URL van een interne dienst zijn. |
Gebruik voor een JSON-array een echte array in to; plaats geen tekenreeks met een JSON-array in een formulierveld. Gebruik verzending naar één ontvanger als eerste integratietest. De ondersteuning voor groepen en MMS verschilt per route, dus controleer vóór gebruik welke combinatie wordt ondersteund.
Lees het volledige resultaat
Alleen enkele geselecteerde velden ter illustratie; de weergegeven kosten zijn geen prijsopgave.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Controleer de HTTP-status, status.code in de JSON en status/message in het antwoord samen. Resultaatcodes kunnen tekenreeksen zijn. Bewaar sms_log_id_ori en de teruggegeven bericht- en referentiewaarden zodat de ondersteuning de bijbehorende gegevens kan koppelen. De verouderde waarden voor uniqueid en pid verschillen per route; leid hun indeling niet af en ga er niet van uit dat het idempotentietokens voor de client zijn.
Success of Message queued duidt normaal gesproken op acceptatie door de geselecteerde route, niet op ontvangst op iemands mobiele telefoon. Een eerste callbackstatus zoals sent bewijst op zichzelf geen definitieve aflevering.
Segmenten en kosten
Gebruik SMS-lengteanalyse voor de volledige definitieve tekst voordat u deze verzendt. SMS-tarieven zijn afhankelijk van de bestemming en de dienst van uw account; toepasselijke providerkosten worden per segment toegevoegd. Het verzendpad telt de tarieven voor ontvangers en de toepasselijke toeslagen bij elkaar op en vermenigvuldigt het resultaat vervolgens met het berekende aantal SMS-segmenten. Voor deze berekening wordt een MMS-aanvraag als één bericht behandeld.
cost en permsg zijn opgemaakte tekenreeksen met geldbedragen in het verouderde antwoordformaat. carrier_fee_usd vermeldt het aandeel providerkosten in USD en is al opgenomen in het berekende verzendtotaal; tel dit niet nogmaals op. Controleer de daadwerkelijke tarieven en de beschikbaarheid van routes voor uw account. De aanvraag dient niet uitsluitend om een prijs op te vragen.
De beoordeelde code schrijft kosten af na succesvolle verzending via het providerpad, maar acceptatie door de provider, lokale opslag en facturering vormen niet één transactie. Er kan een fout of time-out optreden nadat een aanvraag door een achterliggende dienst is geaccepteerd. Er wordt geen idempotentiesleutel voor de client beschikbaar gesteld: hergebruik van dezelfde referentie kan tot een nieuwe verzending en nieuwe kosten leiden.
Lokale aflevering en gemengde resultaten
Lokaal gehoste nummers kunnen met de status accepted worden opgenomen in de inkomende berichtenstroom van MultiTEL zonder verzending via een externe provider. Bij een volledig lokale aanvraag kan het antwoord accepted, message_id, provider en delivery_status bevatten. Lokale acceptatie garandeert niet dat de ingestelde doorstuurbestemming van de ontvanger heeft gewerkt.
Controleer local_delivery_results en partial als deze aanwezig zijn. Een ontvanger kan accepted true tonen terwijl het doorsturen is mislukt. Bij een gemengde aanvraag kunnen ontvangers via de provider de status accepted hebben terwijl het lokale deel is mislukt. Probeer niet automatisch de hele batch opnieuw te verzenden: stel eerst per ontvanger vast wat het resultaat was.
Bij volledig lokale acceptatie meldt dit verwerkingspad nul uitgaande kosten, terwijl ontvangers nog steeds hun normale kosten voor inkomende berichten kunnen hebben. Beschouw nul uitgaande kosten niet als garantie dat geen enkel account kosten in rekening krijgt.
Callbacks en correlatie
Wanneer notifyurl wordt meegegeven, bevat de eerste callback een status-omhulsel en antwoordvelden waaronder message_id, reference, from, to, status, status_text, error_code, timestamp en accepted. Ook lokale resultaten kunnen aanwezig zijn. Bewaar correlatiegegevens zonder API-inloggegevens of onnodige berichtinhoud te loggen.
Deze verwerkingsroutine voegt geen ondertekeningsveld toe aan die eerste callback. Gebruik een niet-geverifieerde callback niet als zelfstandige autorisatie voor een andere handeling. Raadpleeg de ondersteunde integratie- of webhookconfiguratie voor uw account en vergelijk onzekere resultaten met de registraties in het portaal of vraag de ondersteuning om hulp. Ga er niet van uit dat callbacks slechts eenmaal of in de volgorde van definitieve aflevering aankomen.
Fouten en veilig herstel
Validatiefouten kunnen API-code 403 gebruiken. Afwijzingen op grond van accountgoedkeuring, P2P-beleid en landenbeleid kunnen ook HTTP 403 instellen en een machineleesbare response.code bevatten. Aanvraaglimieten kunnen 429 gebruiken met informatie over opnieuw proberen. Bij een niet-beschikbaar beleid of een fout bij verzending of lokale opslag kan 503 of 500 worden gebruikt; ook een ontoereikend saldo kan in de verouderde verwerking 500 opleveren.
Houd bij 429 rekening met Retry-After en een eventuele waarde van response.retry_after. Verhelp bij afwijzing van het account, de afzender, het land of de ontvanger eerst de oorzaak voordat u het opnieuw probeert. Bewaar bij een time-out of een onduidelijk verzendresultaat het tijdstip van de aanvraag, de referentie en de teruggegeven identificatiegegevens, controleer het portaal en neem contact op met de ondersteuning voordat u opnieuw verzendt. Alleen het ontbreken van een logvermelding bewijst niet dat geen enkele provider de aanvraag heeft geaccepteerd.