NetSfere Public API

Description

Enables an external client to retrieve text messages or attachment meta data. You must call this endpoint via HTTPS using the POST method.

Additionally, this endpoint may be used to poll for the arrival of new messages. Message IDs increase for each new message, so passing the message ID of a previous message (see the msgId parameter) returns new messages created since the previous message.

Parameters

This endpoint requires the following parameters:

The following parameters are optional and may be passed in any combination to refine the data returned by this endpoint. If you pass multiple parameters, this endpoint combines them using a logical "AND" operation.

For example, if you pass "27848" for convId and "212619" for msgId, this endpoint returns zero or more messages from the conversation whose conversation ID is 27848 that were created after the message whose message ID is 212619.

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

Response

If successful, this web service returns an HTTP 200 response whose body contains a JSON-encoded array of objects, where each object represents a single message:

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

If the message contains an attachment, the attachment element contains a second-level JSON object of the form shown in the second message above. You must call the getfile endpoint to retrieve the attachment's binary data.

If an error occurs, this web service returns an HTTP 4XX or HTTP 5XX response whose body contains a JSON object of the following form:

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

Example

Here's how to call this endpoint with curl:

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

Description

Enables an external client to retrieve a message attachment. You must call this endpoint via HTTPS using the POST method.

Parameters

This endpoint requires the following parameters:

The following parameters are required to uniquely identify the attachment to retrieve. Either attachmentId or both convId and msgId must be specified.

Response

If successful, this web service returns an HTTP 200 response and the attachment's raw binary data.

If an error occurs, this web service returns an HTTP 4XX or HTTP 5XX response whose body contains a JSON object of the following form:

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

Example

Here's how to call this endpoint with 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

Description

Enables an external client to send a message in a new conversation or an existing conversation. You must call this endpoint via HTTPS using the POST method.

Parameters

This endpoint requires the following parameters:

To create a new conversation containing the message, pass the following additional parameters:

To append the message to an existing conversation, pass the following parameters:

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

Response

If successful, this web service returns an HTTP 200 response whose body contains a JSON object of the following form:

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

The convId element contains the numeric conversation ID associated with the message. The msgId element contains the numeric message ID assigned to the message.

If an error occurs, this web service returns an HTTP 4XX or HTTP 5XX response whose body contains a JSON object of the following form:

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

Example

Here's how to call this endpoint with 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'

Description

Enables an external client to send a file as an attachment in a new conversation or an existing conversation. You must call this endpoint via HTTPS using the POST method with the Content-Type header set to multipart/form-data.

Parameters

This endpoint requires the following parameters:

To create a new conversation containing the file as an attachment, you must also pass the following additional parameters:

To append the file as an attachment to an existing conversation, you must also pass the following parameters:

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

Response

If successful, this web service returns an HTTP 200 response whose body contains a JSON object of the following form:

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

The convId element contains the numeric conversation ID associated with the message containing the attachment. The msgId element contains the numeric message ID assigned to the message.

If an error occurs, this web service returns an HTTP 4XX or HTTP 5XX response whose body contains a JSON object of the following form:

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

This endpoint does not support thumbnail generation, so image attachments will appear to recipients with a generic attachment icon.

Example

Here's how to call this endpoint with 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'

Description

Enables an external client to register a callback URL. When an important event (such as the arrival of a new message) occurs in the caller's NetSfere account, NetSfere calls this URL.

You must call this endpoint via HTTPS using the POST method (to register a new callback URL or to replace a previously-registered callback URL) or the DELETE method (to destroy a previously-registered callback URL).

Once you register a webhook, NetSfere continues to call the webhook for each event until one of the following occurs:

• You remove the webhook using the DELETE method.
• An admin disables the associated NetSfere account.
• An admin cancels the NetSfere organization.

NetSfere calls the URL only once for each event and ignores the HTTP response code (including 3XX redirect response codes) returned by the URL.

Parameters

This endpoint requires the following parameters:

When using the POST method, you must also pass the following additional parameters:

Response

If successful, this web service returns an HTTP 200 response whose body contains JSON data of the following form:

OK

If an error occurs, this web service returns an HTTP 4XX or HTTP 5XX response whose body contains a JSON object of the following form:

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

Example

Here's how to use curl to register a new webhook with a POST request:

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

Example

Here's how to use curl to delete a previously-registered webhook with a DELETE request:

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

Callback Payload

When an important event (such as the arrival of a new message) occurs, NetSfere will call your callback URL with an HTTPS POST. The body of the POST request will contain JSON-encoded data of the following form:

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

The elements in this JSON object are:

If you wish to retrieve the new message, you may do so by calling the get endpoint with convId and msgId.

NetSfere ignores the response from the callback URL and will not retry the callback if the initial attempt fails.