Öffentliche NetSfere-API

Beschreibung

Ermöglicht es einem externen Client, Textnachrichten oder Metadaten von Anhängen abzurufen. Sie müssen diesen Endpunkt über HTTPS mit der POST-Methode aufrufen.

Darüber hinaus kann dieser Endpunkt verwendet werden, um nach dem Eingang neuer Nachrichten zu fragen. Die Nachrichten-IDs steigen mit jeder neuen Nachricht, sodass die Übergabe der Nachrichten-ID einer früheren Nachricht (siehe Parameter msgId) neue Nachrichten zurückgibt, die seit der vorherigen Nachricht erstellt wurden.

Parameter

Dieser Endpunkt erfordert die folgenden Parameter:

Die folgenden Parameter sind optional und können in beliebiger Kombination übergeben werden, um die von diesem Endpunkt zurückgegebenen Daten zu verfeinern. Wenn Sie mehrere Parameter übergeben, kombiniert dieser Endpunkt diese mit einer logischen "UND“-Operation.

Wenn Sie beispielsweise "27848" für convId und "212619" für msgId übergeben, gibt dieser Endpunkt null oder mehr Nachrichten aus dem Gespräch mit der ID 27848 zurück, die nach der Nachricht mit der Nachrichten-ID 212619 erstellt wurden.

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

Antwort

Bei Erfolg gibt dieser Webdienst eine HTTP 200-Antwort zurück, deren Text einen JSON-kodierten Bereich von Objekten enthält. Dabei stellt jedes Objekt eine einzelne Nachricht dar:

[
   {
      "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
   }
]

Wenn die Nachricht eine Anlage enthält, enthält das Bindungselement ein JSON-Objekt der zweiten Ebene der in der zweiten Nachricht oben dargestellten Form. Sie müssen den Endpunkt getfile aufrufen, um die Binärdaten des Anhangs abzurufen.

Wenn ein Fehler auftritt, gibt dieser Webdienst eine HTTP 4XX- oder HTTP 5XX-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Beispiel

So rufen Sie diesen Endpunkt mit Curl auf:

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

Beschreibung

Ermöglicht es einem externen Client, einen Nachrichtenanhang abzurufen. Sie müssen diesen Endpunkt über HTTPS mit der POST-Methode aufrufen.

Parameter

Dieser Endpunkt erfordert die folgenden Parameter:

Die folgenden Parameter sind erforderlich, um die abzurufende Anlage eindeutig zu identifizieren. Es muss entweder attachmentId oder convId und msgId angegeben werden.

Antwort

Bei Erfolg gibt dieser Webdienst eine HTTP 200-Antwort sowie die Rohbinärdaten des Anhangs zurück.

Wenn ein Fehler auftritt, gibt dieser Webdienst eine HTTP 4XX- oder HTTP 5XX-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Beispiel

So rufen Sie diesen Endpunkt mit Curl auf:

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

oder:

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

Beschreibung

Ermöglicht es einem externen Client, eine Nachricht und eine neue oder vorhandene Conversation zu senden. Sie müssen diesen Endpunkt über HTTPS mit der POST-Methode aufrufen.

Parameter

Dieser Endpunkt erfordert die folgenden Parameter:

Übergeben Sie die folgenden zusätzlichen Parameter, um eine neue Conversation mit der Nachricht zu erstellen:

Um die Nachricht an ein bestehendes Gespräch anzuhängen, übergeben Sie die folgenden Parameter:

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

Antwort

Bei Erfolg gibt dieser Webdienst eine HTTP 200-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Das Element convId enthält die mit dieser Nachricht verknüpfte numerische Gesprächs-ID. Das Element msgId enthält die der Nachricht zugeordnete numerische Nachrichten-ID.

Wenn ein Fehler auftritt, gibt dieser Webdienst eine HTTP 4XX- oder HTTP 5XX-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Beispiel

So rufen Sie diesen Endpunkt mit Curl auf:

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'

Beschreibung

Ermöglicht es einem externen Client, eine Datei als Anhang in einer neuen oder vorhandenen Conversation zu versenden. Sie müssen diesen Endpunkt über HTTPS mit der POST-Methode aufrufen, wobei der Content-Type-Header auf multipart/form-data gesetzt ist.

Parameter

Dieser Endpunkt erfordert die folgenden Parameter:

Übergeben Sie auch die folgenden zusätzlichen Parameter, um eine neue Conversation mit der Datei als Anhang zu erstellen:

Um die Datei an ein bestehendes Gespräch anzuhängen, übergeben Sie auch die folgenden Parameter:

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

Antwort

Bei Erfolg gibt dieser Webdienst eine HTTP 200-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Das Element convId enthält die mit dieser Nachricht und dem darin enthaltenen Anhang verknüpfte numerische Gesprächs-ID. Das Element msgId enthält die der Nachricht zugeordnete numerische Nachrichten-ID.

Wenn ein Fehler auftritt, gibt dieser Webdienst eine HTTP 4XX- oder HTTP 5XX-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Dieser Endpunkt unterstützt die Generierung von Miniaturansichten nicht, so dass Bildanhänge bei Empfängern mit einem generischen Anhänge-Symbol angezeigt werden.

Beispiel

So rufen Sie diesen Endpunkt mit Curl auf:

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'

Beschreibung

Ermöglicht es einem externen Client, eine Rückruf-URL zu registrieren. Wenn im NetSfere-Konto des Anrufers ein wichtiges Ereignis eintritt (z. B. der Eingang einer neuen Nachricht), ruft NetSfere diese URL auf.

Sie müssen diesen Endpunkt über HTTPS aufrufen. Wählen Sie dazu die POST-Methode (um eine neue Rückruf-URL zu registrieren oder eine zuvor registrierte Rückruf-URL zu ersetzen) oder die DELETE-Methode (um eine zuvor registrierte Ruckruf-URL zu löschen).

Nachdem Sie einen Webhook registriert haben, ruft NetSfere bei jedem Ereignis den Webhook auf, bis einer der folgenden Fälle eintritt:

• Sie entfernen den Webhook mit der DELETE-Methode.
• Ein Administrator deaktiviert das zugehörige NetSfere-Konto.
• Ein Administrator hebt die NetSfere-Organisation auf.

NetSfere ruft die URL nur einmal pro Ereignis auf und ignoriert den von der URL zurückgegebenen HTTP-Antwortcode (einschließlich 3XX-Weiterleitungscodes).

Parameter

Dieser Endpunkt erfordert die folgenden Parameter:

Bei Verwendung der POST-Methode müssen Sie außerdem die folgenden Parameter übergeben:

Antwort

Bei Erfolg gibt dieser Webdienst eine HTTP 200-Antwort zurück, deren Text folgendermaßen formatierte JSON-Daten enthält:

OK

Wenn ein Fehler auftritt, gibt dieser Webdienst eine HTTP 4XX- oder HTTP 5XX-Antwort zurück, deren Text ein JSON-Objekt der folgenden Form enthält:

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

Beispiel

So registrieren Sie einen neuen Webhook über Curl mithilfe der POST-Anforderung:

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

Beispiel

So löschen Sie einen zuvor registrierten Webhook über Curl mithilfe der DELETE-Anforderung:

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

Rückruf-Payload

Wenn ein wichtiges Ereignis (z. B. das Eintreffen einer neuen Nachricht) eintritt, ruft NetSfere Ihre Callback-URL mit einem HTTPS-POST auf. Der Text der POST-Anforderung enthält JSON-kodierte Daten in der folgenden Form:

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

Die Elemente in diesem JSON-Objekt sind:

Falls Sie die neue Nachricht abrufen wollen, können Sie dies tun, indem Sie den get- Endpunkt mit convId und msgIdanrufen.

NetSfere ignoriert die Antwort von der Callback-URL und wird nicht versuchen, den Callback erneut durchzuführen, falls der erste Versuch fehlschlägt.