Openbare NetSfere-API

Beschrijving

Hiermee kan een externe client tekstberichten of metadata van bijlagen ophalen. U moet dit eindpunt via HTTPS met de methode POST aanroepen.

Bovendien kan dit eindpunt worden gebruikt om te controleren op de aankomst van nieuwe berichten. Bericht-ID\'s worden verhoogd voor elk nieuw bericht. Als u de bericht-ID van een vorig bericht doorgeeft (zie de parameter msgId), worden dus nieuwe berichten geretourneerd die zijn gemaakt sinds het vorige bericht.

Parameters

Voor dit eindpunt zijn de volgende parameters vereist:

De volgende parameters zijn optioneel en kunnen in elke combinatie worden doorgegeven om de gegevens die door dit eindpunt worden geretourneerd, te verfijnen. Als u meerdere parameters doorgeeft, worden deze met dit eindpunt gecombineerd met een logische \'EN\'-bewerking.

Als u bijvoorbeeld \'27848\' voor convId en \'212619\' voor msgId doorgeeft, worden met dit eindpunt nul of meer berichten geretourneerd van het gesprek waarvan de gespreks-ID 27848 is die is gemaakt na het bericht waarvan het bericht-ID 212619 is.

https://web.netsfere.com/#chat/27848

Antwoord

Als dit lukt, retourneert deze webservice een HTTP 200-antwoord waarvan het hoofdgedeelte een JSON-gecodeerde array van objecten bevat, waarbij elk object één bericht vertegenwoordigt:

[
   {
      "msgId": 212619,
      "convId": 27848,
      "created": 1516655475,
      "senderEmail": "user1@email.com",
      "msgType": "text",
      "msgText": "A man's home is his castle.",
      "attachment": null,
      "quotedMsgId": 0,
      "locationData": null,
      "isForwarded": false,
      "priority": "normal",
      "isDeleted": false
   },
   {
      "msgId": 212620,
      "convId": 27848,
      "created": 1516656257,
      "senderEmail": "user1@email.com",
      "msgType": "attachment",
      "msgText": "",
      "attachment": {
         "attachmentId":"5a66542c8e77a",
         "fileName":"castle.jpg",
         "fileSize":242560,
         "mimeType":"image\/jpeg"},
      "quotedMsgId": 0,
      "locationData": null,
      "isForwarded": true,
      "priority": "normal",
      "isDeleted": false
   },
   {
      "msgId": 212621,
      "convId": 27848,
      "created": 1516666257,
      "senderEmail": "user1@email.com",
      "msgType": "location",
      "msgText": "loc:42.1341247,-88.0035324",
      "attachment": null,
      "quotedMsgId": 0,
      "locationData": {
         "address": "Infinite Convergence, North Wilke Road, Arlington Heights, IL, USA",
         "isMyLocation": true
      },
      "isForwarded": false,
      "priority": "normal",
      "isDeleted": false
   }
]

Als het bericht een bijlage bevat, bevat het attachment-element een JSON-object van het tweede niveau van het formulier dat wordt weergegeven in het tweede bericht hierboven. U moet het eindpunt getfile aanroepen om de binaire gegevens van de bijlage op te halen.

Als er een fout optreedt, retourneert deze webservice een HTTP 4XX- of HTTP 5XX-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "error": "Missing parameter: \"email\""
}

Voorbeeld

Zo kunt u dit eindpunt aanroepen met cURL:

curl -i 'https://api.netsfere.com/get' \
--data 'email=user1@email.com&password=123&msgId=212619'

Beschrijving

Hiermee kan een externe client een berichtbijlage ophalen. U moet dit eindpunt via HTTPS met de methode POST aanroepen.

Parameters

Voor dit eindpunt zijn de volgende parameters vereist:

De volgende parameters zijn vereist voor een unieke identificatie van de bijlage die moet worden opgehaald. attachmentId of zowel convId als msgId moet worden opgegeven.

Antwoord

Als dit lukt, retourneert deze webservice een HTTP 200-antwoord en de onbewerkte binaire gegevens van de bijlage.

Als er een fout optreedt, retourneert deze webservice een HTTP 4XX- of HTTP 5XX-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "error": "Missing parameter: \"email\""
}

Voorbeeld

Zo kunt u dit eindpunt aanroepen met cURL:

curl -i 'https://api.netsfere.com/getfile' \
--data 'email=user1@email.com&password=123&attachmentId=5a66542c8e77a' -o castle.jpg

of:

curl -i 'https://api.netsfere.com/getfile' \
--data 'email=user1@email.com&password=123&convId=1000&msgId=123456' -o castle.jpg

Beschrijving

Hiermee kan een externe client een bericht verzenden in een nieuw gesprek of een bestaand gesprek. U moet dit eindpunt via HTTPS met de methode POST aanroepen.

Parameters

Voor dit eindpunt zijn de volgende parameters vereist:

Geef de volgende aanvullende parameters door om een ​​nieuw gesprek te maken dat het bericht bevat:

Als u het bericht wilt toevoegen aan een bestaand gesprek, geeft u de volgende parameters door:

https://web.netsfere.com/#chat/27848

Antwoord

Als dit lukt, retourneert deze webservice een HTTP 200-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "convId": 1000,
   "msgId": 123456
}

Het element convId bevat de numerieke gespreks-ID die aan het bericht is gekoppeld. Het element msgId bevat de numerieke bericht-ID die aan het bericht is toegewezen.

Als er een fout optreedt, retourneert deze webservice een HTTP 4XX- of HTTP 5XX-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "error": "Missing parameter: \"email\""
}

Voorbeeld

Zo kunt u dit eindpunt aanroepen met cURL:

curl -i 'https://api.netsfere.com/send' \
--data 'email=user1@email.com&password=123&msgText=This is a test.&convTitle=Hello World!&participants=user2@email.com,user3@email.com'

Beschrijving

Hiermee kan een externe client een bericht als een bijlage verzenden in een nieuw gesprek of een bestaand gesprek. U moet dit eindpunt via HTTPS met de methode POST aanroepen waarbij de koptekst Content-Type is ingesteld op multipart/form-data.

Parameters

Voor dit eindpunt zijn de volgende parameters vereist:

Geef de volgende aanvullende parameters door om een nieuw gesprek te maken dat het bestand als een bijlage bevat:

Als u het bericht als bijlage wilt toevoegen aan een bestaand gesprek, moet u ook de volgende parameters doorgeven:

https://web.netsfere.com/#chat/27848

Antwoord

Als dit lukt, retourneert deze webservice een HTTP 200-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "convId": 1000,
   "msgId": 123456
}

Het element convId bevat de numerieke gespreks-ID die is gekoppeld aan het bericht dat de bijlage bevat. Het element msgId bevat de numerieke bericht-ID die aan het bericht is toegewezen.

Als er een fout optreedt, retourneert deze webservice een HTTP 4XX- of HTTP 5XX-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "error": "Missing parameter: \"email\""
}

Dit eindpunt ondersteunt geen miniatuurweergave, waardoor beeldbijlagen verschijnen voor ontvangers met een generiek bijlagepictogram.

Voorbeeld

Zo kunt u dit eindpunt aanroepen met cURL:

curl -i 'https://api.netsfere.com/sendfile' \
-F 'email=user1@email.com' \
-F 'password=123' \
-F 'convTitle=Hello World!' \
-F 'participants=user2@email.com,user3@email.com' \
-F 'msgText=My example' \
-F 'uploadFile=@path/to/my/example.png'

Beschrijving

Hiermee kan een externe client een terugbel-URL registreren. Wanneer een belangrijke gebeurtenis zich voordoet in het NetSfere-account van de beller (zoals een nieuw bericht dat aankomt), belt NetSfere deze URL op.

U moet dit eindpunt via HTTPS aanroepen met de methode POST (om een nieuwe terugbel-URL te registreren of een eerder geregistreerde terugbel-URL te vervangen) of met de methode DELETE (om een eerder geregistreerde terugbel-URL te vernietigen).

Zodra u een webhook heeft geregistreerd, blijft NetSfere de webhook voor elke gebeurtenis opbellen tot een van de volgende zaken zich voordoet:

• U verwijdert de webhook met behulp van de methode DELETE.
• Een beheerder deactiveert het gekoppelde NetSfere-account.
• Een beheerder annuleert de NetSfere-organisatie.

NetSfere belt de URL slechts eenmaal op voor elke gebeurtenis en negeert de HTTP-responscode (inclusief responscodes 3XX voor omleiding) die door de URL wordt geretourneerd.

Parameters

Voor dit eindpunt zijn de volgende parameters vereist:

Bij gebruik van de methode POST moet u ook de volgende aanvullende parameters doorlopen:

Antwoord

Als de bewerking slaagt, retourneert deze webservice een HTTP 200-antwoord waarvan het hoofdgedeelte JSON-gegevens met de volgende vorm bevat:

OK

Als er een fout optreedt, retourneert deze webservice een HTTP 4XX- of HTTP 5XX-antwoord waarvan het hoofdgedeelte een JSON-object met de volgende vorm bevat:

{
   "error": "Missing parameter: \"email\""
}

Voorbeeld

Zo gebruikt u cURL om een nieuwe webhook te registreren met een POST-verzoek:

curl -i 'https://api.netsfere.com/webhook' \
--data 'email=user1@email.com&password=123&callbackUrl=https://example.com/my/path?myparam=1000'

Voorbeeld

Zo gebruikt u cURL om een nieuwe webhook te verwijderen met een DELETE-verzoek:

curl -i -X DELETE 'https://api.netsfere.com/webhook' \
--data 'email=user1@email.com&password=123'

Payload van callback

Wanneer een belangrijke gebeurtenis (zoals het arriveren van een nieuw bericht) plaatsvindt, roept NetSfere uw callback-URL aan met een HTTPS POST. Het POST-verzoek bevat JSON gecodeerde data in de volgende vorm:

{
   "convId": 1000,
   "msgId": 123456,
   "senderEmail": "user1@email.com",
   "uuid": "93450918-75fe-11eb-a7fe-00505604a731"
}

De elementen in dit JSON-object zijn:

Als u het nieuwe bericht wilt ophalen, kunt u dit doen door een get-opdracht voor het endpoint convId en msgId.

NetSfere negeert het antwoord van de callback-URL en probeert de callback niet opnieuw als de eerste poging mislukt.