API pública de NetSfere

Descripción

Permite que un cliente externo recupere mensajes de texto o metadatos adjuntos. Debe llamar a este punto final a través de HTTPS utilizando el método POST.

Además, este extremo se puede usar para sondear la llegada de nuevos mensajes. Los ID de mensaje aumentan con cada mensaje nuevo, por lo que pasar el ID de mensaje de un mensaje anterior (consulte el parámetro msgId) devuelve nuevos mensajes creados desde el mensaje anterior.

Parámetros

Este punto final requiere los siguientes parámetros:

Los siguientes parámetros son opcionales y se pueden pasar en cualquier combinación para refinar los datos devueltos por este extremo. Si pasa varios parámetros, este extremo los combina mediante una operación lógica "Y".

Por ejemplo, si pasa "27848" para convId y "212619" para msgId, este extremo devuelve cero o más mensajes de la conversación cuyo ID de conversación es 27848 que se crearon después del mensaje cuyo ID de mensaje es 212619.

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

Respuesta

Si tiene éxito, este servicio web devuelve una respuesta HTTP 200 cuyo cuerpo contiene una matriz de objetos codificados en JSON, donde cada objeto representa un único mensaje:

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

Si el mensaje contiene un archivo adjunto, el elemento attachment contiene un objeto JSON de segundo nivel con el formato que se muestra en el segundo mensaje anterior. Debe llamar al extremo getfile para recuperar los datos binarios del archivo adjunto.

Si ocurre un error, este servicio web devuelve una respuesta HTTP 4XX o HTTP 5XX cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

Ejemplo

Aquí se explica cómo llamar a este extremo con curl:

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

Descripción

Permite que un cliente externo recupere un archivo adjunto de mensaje. Debe llamar a este punto final a través de HTTPS utilizando el método POST.

Parámetros

Este punto final requiere los siguientes parámetros:

Los siguientes parámetros son necesarios para identificar de forma exclusiva el archivo adjunto que se va a recuperar. Se debe especificar attachmentId o ambos convId y msgId.

Respuesta

Si tiene éxito, este servicio web devuelve una respuesta HTTP 200 y los datos binarios sin procesar del archivo adjunto.

Si ocurre un error, este servicio web devuelve una respuesta HTTP 4XX o HTTP 5XX cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

Ejemplo

Aquí se explica cómo llamar a este extremo con curl:

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

or:

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

Descripción

Permite que un cliente externo envíe un mensaje en una conversación nueva o existente. Debe llamar a este punto final a través de HTTPS utilizando el método POST.

Parámetros

Este punto final requiere los siguientes parámetros:

Para crear una nueva conversación que contenga el mensaje, pase los siguientes parámetros adicionales:

Para agregar el mensaje a una conversación existente, pase los siguientes parámetros:

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

Response

Si tiene éxito, este servicio web devuelve una respuesta HTTP 200 cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

El elemento convId contiene el ID de conversación numérico asociado con el mensaje. El elemento msgId contiene el ID de mensaje numérico asignado al mensaje.

Si ocurre un error, este servicio web devuelve una respuesta HTTP 4XX o HTTP 5XX cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

Example

Aquí se explica cómo llamar a este extremo con 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'

Descripción

Permite que un cliente externo envíe un archivo como adjunto en una conversación nueva o existente. Debe llamar a este punto final a través de HTTPS utilizando el método POST con el encabezado Content-Type establecido en multipart/form-data.

Parámetros

Este punto final requiere los siguientes parámetros:

Para crear una nueva conversación que contenga el archivo como archivo adjunto, también debe pasar los siguientes parámetros adicionales:

Para agregar el archivo como archivo adjunto a una conversación existente, también debe pasar los siguientes parámetros:

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

Respuesta

Si tiene éxito, este servicio web devuelve una respuesta HTTP 200 cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

El elemento convId contiene el ID de conversación numérico asociado con el mensaje que contiene el archivo adjunto. El elemento msgId contiene el ID de mensaje numérico asignado al mensaje.

Si ocurre un error, este servicio web devuelve una respuesta HTTP 4XX o HTTP 5XX cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

Este punto final no admite la generación de miniaturas, por lo que los archivos adjuntos de imágenes se mostrarán a los destinatarios con un ícono de archivo adjunto genérico.

Ejemplo

Aquí se explica cómo llamar a este extremo con 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'

Descripción

Permite que un cliente externo registre una URL de devolución de llamada. Cuando ocurre un evento importante (como la llegada de un nuevo mensaje) en la cuenta de NetSfere de la persona que llama, NetSfere llama a esta URL.

Debe llamar a este punto final a través de HTTPS usando el método POST (para registrar una nueva URL de devolución de llamada o para reemplazar una URL de devolución de llamada registrada previamente) o el método DELETE (para destruir una URL de devolución de llamada previamente registrada).

Una vez que registra un webhook, NetSfere continúa llamando al webhook para cada evento hasta que ocurra uno de los siguientes:

• Elimine el webhook usando el método DELETE.
• Un administrador desactiva la cuenta de NetSfere asociada.
• Un administrador cancela la organización de NetSfere.

NetSfere llama a la URL solo una vez para cada evento e ignora el código de respuesta HTTP (incluidos los códigos de respuesta de redireccionamiento 3XX) devuelto por la URL.

Parámetros

Este punto final requiere los siguientes parámetros:

Al usar el método POST, también debe pasar los siguientes parámetros adicionales:

Respuesta

Si tiene éxito, este servicio web devuelve una respuesta HTTP 200 cuyo cuerpo contiene datos JSON de la siguiente forma:

OK

Si ocurre un error, este servicio web devuelve una respuesta HTTP 4XX o HTTP 5XX cuyo cuerpo contiene un objeto JSON de la siguiente forma:

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

Ejemplo

Aquí se explica cómo usar curl para registrar un nuevo webhook con una solicitud POST:

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

Ejemplo

Aquí se explica cómo usar curl para eliminar un webhook registrado previamente con una solicitud DELETE:

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

Carga útil de devolución de llamada

Cuando ocurre un evento importante (como la llegada de un nuevo mensaje), NetSfere llamará a su URL de devolución de llamada con un HTTPS POST. El cuerpo de la solicitud POST contendrá datos codificados en JSON de la siguiente forma:

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

Los elementos de este objeto JSON son:

Si desea recuperar el nuevo mensaje, puede hacerlo llamando al extremo get con convId y msgId.

NetSfere ignora la respuesta de la URL de devolución de llamada y no volverá a intentar la devolución de llamada si falla el intento inicial.