API Docs

The API docs describes the Http API interfaces provided by the Solaiemes RCS Solution Gateway. The API instantiates and controls a virtual RCS client impersonating a service on top of a RCS-enabled core.

On the right, you can browse on the different sections to find easily the calls you need.

Long polling is a technique that allows information push from a server to a client. The server provides to each application a notifications URL that the application must keep open, listening for notifications. The server holds the client request and waits for some information to be available. The application request is held by the server until some information is available, until a timer expires or at server discretion. After the connection is closed (because a response is sent by the server or any other reason), the application must re-open the connection and wait for the next notification. If some notification can’t be sent while the connection is closed, it will be kept in a queue by the server until the application re-opens the connection.

It is important to note that URL parameters must be encoded using “ISO-8859-1” charset.

HTTP GET https://{serverRoot}/notifications

Parameters:
- username: identifier of the user to be registered.
- token: authentication token string.

Response: 200 status code, back a notification in the corresponding HTTP response or a 4xx code if an error happened.

HTTP Example:

GET /SERVER_ROOT/notifications?username=USERNAME HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X GET "https://SERVER_ROOT/notifications?username=USERNAME?token=TOKEN"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This operation logs the virtual RCS user into RCS Core; it can be understood as the operation to deploy the application. It should be invoked only once in an application lifetime.

A SIP REGISTER request is sent to the RCS Core, between other actions. A result code equals to 0 means that the REGISTER was successfully sent. Any other result code means that there was an error sending the REGISTER.

In any case, this result code only refers to the REGISTER request, not the IMS core response.

After the registerSuccess event, the OPTIONS polling will be started.

HTTP POST https://{serverRoot}/session

Body:
- username: identifier of the user to be registered.
- token: authentication token string.
- action: register

Response: 200 status, response contains a result code: information about success/failure of the user registration.

HTTP Example:

POST /SERVER_ROOT/session HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=register&username=USERNAME&token=TOKEN

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/session" -d "action=register&username=USERNAME&token=TOKEN"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This operation logs the virtual RCS user out from the RCS Core, it can be understood as the operation to un-deploy the application. Once is completed, the application is no longer connected to the RCS core. It should be invoked only once in an application lifetime.

As with the register operation, a REGISTER request is sent to the RCS Core. A result code equals to 0 means that it was successfully sent and any other result code means that there was an error sending it.

HTTP POST https://{serverRoot}/session

Body:
- username: identifier of the user to be de-registered.
- token: authentication token string.
- action: unregister

Response: 200 status, response contains a result code: information about success/failure of the user de-registration.

HTTP Example:

POST /SERVER_ROOT/session HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=unregister&username=USERNAME&token=TOKEN

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/session" -d "action=unregister&username=USERNAME&token=TOKEN"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This notification group is related to the results of register and unregister attempts. The RCS solution gateway will send a notification using the URL configured for the corresponding virtual client.

Register success:
The registerSuccess notification will be sent when the virtual client receives a 200 OK to a REGISTER attempt. Notice that refresh REGISTERs are also included, so if there is not any problem, this notification will be sent periodically.
Parameters:
* username: the identifier of the user that tried to register.

Register error:
The registerError notification will be sent when the virtual client receives an unexpected error response to a REGISTER attempt. Notice that refresh REGISTERs are also included, so if there is not any problem, this notification will not be sent.
Parameters:
* username: the identifier of the user that tried to register.

Unregister success:
The unregisterSuccess notification will be sent when the virtual client receives a 200 OK response to an un-REGISTER attempt.
Parameters:
* username: the identifier of the user that tried to unregister.

Unregister error:
The unregisterError notification will be sent when the virtual client receives an unexpected error response to an un-REGISTER attempt.
Parameters:
* username: the identifier of the user that tried to unregister.

Get the up-to-date list of contacts of a user. Every contact has information like the uri (sip or tel), the displayname, the status, the capabilities it has, and if the information is updated or not.

HTTP GET https://{serverRoot}/contactsrcse

Parameters:
- username: identifier of the user whose contacts are to be retrieved.
- token: authentication token string.
- action: getContactList

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

GET /SERVER_ROOT/contactsrcse?action=getContactList&username=USERNAME&token=TOKEN HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X GET "https://SERVER_ROOT/contactsrcse?action=getContactList&username=USERNAME&token=TOKEN"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Get the detailed information of a contact. This detailed information is the contact's uri, displayname and last capabilities received. If the contact's capabilities are not updated when the getContact action is received, then the result will contain a set of capabilities that will be out of date. However an OPTIONS request to the contact will be sent and the updated capabilities will be available to check.

HTTP GET https://{serverRoot}/contactsrcse

Parameters:
- username: identifier of the user whose contact want to be retrieved.
- token: authentication token string.
- contactId: uri of the contact we want to retrieve.
- action: getContactList

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

GET /SERVER_ROOT/contactsrcse?action=getContact&username=USERNAME&token=TOKEN& contactId=CONTACT_ID HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X GET "https://SERVER_ROOT/contactsrcse?action=getContactList&username=USERNAME&token=TOKEN&contactId=CONTACT_ID"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Add a contact to the contact list of the selected user.

HTTP POST https://{serverRoot}/contactsrcse

Body:
- username: identifier of the user to be unregistered.
- token: authentication token string.
- contactDisplayName: name of the contact to be displayed at the user display.
- msisdn: Mobile Station Integrated Services Digital Network (the phone number).
- uri: uri identifying the destination user.
msisdn or uri parameters may be used, but not both.
- action: addContact

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/contactsrcse HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=addContact&username=USERNAME&token=TOKEN&uri=CONTACT_ID&contactDisplayName=CONTACT_DISPLAYNAME

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/contactsrcse" -d "action=addContact&username=USERNAME&token=TOKEN&uri=CONTACT_URI&contactDisplayName=CONTACT_DISPLAYNAME"

- CONTACT_DISPLAYNAME: name of the contact to be displayed at the user display.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN, CONTACT_MSISDN and CONTACT_URI, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Edit a contact to the contact list of the selected user.

HTTP POST https://{serverRoot}/contactsrcse

Body:
- username: identifier of the user who wants to edit a contact from his own list.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the contact to be edited.
- contactDisplayName: name of the contact to be displayed at the user display.
- action: editContact

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/contactsrcse HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=editContact&username=USERNAME&contactId=CONTACT_ID&contactDisplayName=CONTACT_DISPLAYNAME

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/contactsrcse" -d "action=editContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&contactDisplayName=CONTACT_DISPLAYNAME"

- CONTACT_DISPLAYNAME: name of the contact to be displayed at the user display.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Remove a contact from the RCS contact list of the selected user. Once the invocation is finished we can check the result code to determinate if the contact was successfully removed.

HTTP POST https://{serverRoot}/contactsrcse

Body:
- username: identifier of the user who wants to delete a contact from his own list.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the contact to be deleted.
- action: removeContact

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/contactsrcse HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=removeContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/contactsrcse" -d "action=removeContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Block a contact from the RCS contact list of the selected user. Once the invocation is finished we can check the result code to determinate if the contact was successfully blocked.

HTTP POST https://{serverRoot}/contactsrcse

Body:
- username: identifier of the user who wants to block a contact from his own list.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the contact be blocked.
- action: blockContact

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/contactsrcse HTTP/1.1 Accept: */* app_id:APP_ID app_key:app_key Content-Type: application/x-www-form-urlencoded action=blockContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/contactsrcse" -d "action=blockContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Accepts a contact from the RCS contact list of the selected user.

HTTP POST https://{serverRoot}/contactsrcse

Body:
- username: identifier of the user who wants to accepte a contact.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the contact be accepted.
- contactDisplayName: it changes the displayname of the contact.
- action: acceptContact

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/contactsrcse HTTP/1.1 Accept: */* app_id:APP_ID app_key:app_key Content-Type: application/x-www-form-urlencoded action=acceptContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/contactsrcse" -d "action=acceptContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&contactDisplayName=CONTACT_DISPLAYNAME"

- CONTACT_DISPLAYNAME: it changes the displayname of the contact.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This notification group is related to changes in the virtual client contacts. It's available only for RCS-e virtual clients.

Contact added:
The contactAdded notification will be sent when the virtual client adds a contact successfully.
Parameters:
* username: the identifier of the user who the contact belongs to.
* contactId: uri (sip or tel) identifying the contact.
* displayname: friendly name used by the contact.
* capabilitiesUpdated: it is a boolean value (true or false).
* rcsECapabilities: contains a list with the capabilities.
* relationship: it has 3 possible values: "unknown", "accepted", "blocked".
* status: it has 4 possible values: "online", "offline", "not_rcs", "unknown".

Contact changed:
The contactChanged notification will be sent when a contact changes.
Parameters:
* username: the identifier of the user who the contact belongs to.
* contactId: uri (sip or tel) identifying the contact.
* displayname: friendly name used by the contact.
* capabilitiesUpdated: it is a boolean value (true or false).
* rcsECapabilities: contains a list with the capabilities.
* relationship: it has 3 possible values: "unknown", "accepted", "blocked".
* status: it has 4 possible values: "online", "offline", "not_rcs", "unknown".

Contact removed:
The contactRemoved notification will be sent when a contact is removed successfully.
Parameters:
* username: the identifier of the user who the contact belongs to.
* contactId: uri (sip or tel) identifying the contact.

This is the way to create a chat session if the user has enabled the option of session self-management.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who wants to send a chat message.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the destination user.
- message: message content
- action: sendIMMessageAutomaticSession

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=sendIMMessageAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&message=Hello

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat" -d "action=sendIMMessageAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&message=TEXT"

- TEXT: message


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This method is used to accept IM notifications with an automatic session.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who is asking the messages he has received.
- token: authentication token string.
- contactId: tel or sip uri of the contact.
- action: acceptIMInvitationAutomaticSession

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=acceptIMInvitationAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat" -d "action=acceptIMInvitationAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN, and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Terminate the selected chat session. SIP BYE request is sent to remote party. This call needs to add the identification of the contact.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who wants to close a chat.
- token: authentication token string.
- contactId: tel or sip uri of the contact.
- action: closeChatAutomaticSession

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=closeChatAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat?action=closeChatAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This method is used to decline IM notifications with an automatic session.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who is asking the messages he has received.
- token: authentication token string.
- contactId: tel or sip uri of the contact.
- action: declineIMInvitationAutomaticSession

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=declineIMInvitationAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat" -d "action=declineIMInvitationAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID"


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

Send an “is composing” message to the contact you are chatting with. This allows a user in a chat session to see when another user is typing a new message/reaction. It is needed to have established a session to use this method.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who wants to receive messages.
- token: authentication token string.
- contactId: tel or sip uri of the contact.
- lastActive: provide the information that about when the user has been seen on-line last time.
- refresh: indicates the time while the send composing information is valid.
- state: active or idle
- action: sendIsComposingtoContact

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=sendIsComposingAutomaticSession&refresh=120&state=idle&lastActive=1396862262363&username=USERNAME& token=TOKEN&contactId=CONTACT_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat" -d "action=sendIsComposingtoContact&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&lastActive=ONLINE_LAST_TIME&refresh=VALID_TIME&state=STATE"

- ONLINE_LAST_TIME: on-line last time. Must be a valid date in long format.
- VALID_TIME: second time value.
- STATE: active / idle


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This method is used to send display notifications.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who is asking the messages he has received.
- token: authentication token string.
- messageId: message identifier in which we want to send the display notification.
- action: sendDisplayNotification

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=sendDisplayNotificationAutomaticSession&username=USERNAME&token=TOKEN&messageId=MESSAGE_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat" -d "action=sendDisplayNotificationAutomaticSession&username=USERNAME&token=TOKEN&messageId=MESSAGE_ID"

- MESSAGE_ID: the value of this parameter is obtained from the notification channel.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This notification group is related to events for instant messaging.

Receive message:
The receiveMessage notification will be sent when the virtual client receives an instant message.
Parameters:
* username: the identifier of the user that receives the message.
* contactId: the URI of the user sending the message.
* sessionId: identifier of the current chat session.
* date: the date message received information (long).
* message: the text message received information.

Receive delivery:
The receiveDeliveryNotification notification will be sent when the message sent is received by the other side.
Parameters:
* username: the identifier of the user that receives the message.
* messageId: identifier of the current message.

Receive display:
The receiveDisplayNotification notification will be sent when the message sent is displayed by the other side.
Parameters:
* username: the identifier of the user that receives the message.
* messageId: identifier of the current message.

Is Composing received:
The isComposingReceived notification when the other side is writing a message.
Parameters:
* username: the identifier of the user that receives the message.
* sessionId: identifier of the current chat session.
* lastActive: the moment when the user has been seen on-line last time.
* refresh: time that is active.
* state: it can be Active or Idle, depending if it is writing a message or not.

IM Session closed:
The imSessionClosed notification will be sent when an established IM session is closed.
Parameters:
* username: the identifier of the user that receives the notification.
* sessionId: the identifier of the session that has been closed.
* contactId: the identifier of the contact that has closed the session.

IM Invitation received:
The imInvitationReceived notification will be sent when an established IM invitation is received.
Parameters:
* username: the identifier of the user that receives the invitation.
* sessionId: the identifier of the session of the invitation received.
* contactId: the identifier of the contact that has sent the invitation.

IM Invitation error:
The imInvitationError notification will be sent when an IM invitation has not succeeded.
Parameters:
* username: the identifier of the user that receives the invitation.
* sessionId: the identifier of the session of the invitation received.

IM Invitation success:
The imInvitationSuccess notification will be sent when an IM invitation has succeeded.
Parameters:
* username: the identifier of the user that receives the invitation.
* sessionId: the identifier of the session of the invitation received.

It sends an url located file to a contact.

HTTP POST https://{serverRoot}/filetransfer

Body:
- username: identifier of the user who wants to send a file.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the destination user.
- contentType: ontent type of the file.
- filename: name of file to send.
- fileUrl: url where the file is located.
- subject: subject to be included in the session.
- action: sendFile

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/filetransfer HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=sendFile&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&subject=file&contentType=image/jpeg& filename=linux&fileUrl=https://tux.crystalxp.net/png/brightknight-doraemon-tux-3704.png

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/filetransfer" -d "action=sendFile&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&subject=SUBJECT_MESSAGE&contentType=CONTENT_TYPE&filename=FILE_NAME&fileUrl=FILE_URL"

- SUBJECT_MESSAGE: message subject
- CONTENT_TYPE: this value indicates the media type of the message content (example: image/jpeg, text/plain...).
- FILE_NAME: it is the name used to identify the file.
- FILE_URL: public url access a file (https not permitted).


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

It sends a file including the file content codified as a base64 string in the request.

HTTP POST https://{serverRoot}/filetransfer

Body:
- username: identifier of the user who wants to send a file.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the destination user.
- contentType: content type of the file.
- filename: name of file to send.
- data: the file encoded as a base64 string.
- subject: subject to be included in the session.
- action: sendFileData

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/filetransfer HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Expect: 100-continue Content-Type: multipart/form-data; boundary=----------------------------60b7133771dd HTTP/1.1 100 Continue ------------------------------60b7133771dd Content-Disposition: form-data; name="action" sendFileData ------------------------------60b7133771dd Content-Disposition: form-data; name="username" USERNAME ------------------------------60b7133771dd Content-Disposition: form-data; name="token" TOKEN ------------------------------60b7133771dd Content-Disposition: form-data; name="contactId" CONTACT_ID ------------------------------60b7133771dd Content-Disposition: form-data; name="subject" file ------------------------------60b7133771dd Content-Disposition: form-data; name="contentType" image/jpg ------------------------------60b7133771dd Content-Disposition: form-data; name="filename" icon ------------------------------60b7133771dd Content-Disposition: form-data; name="data"; filename="icon.jpg" Content-Type: image/jpeg ......JFIF......................... .. ..... ."" ...$(4,$&1'..-=5157:4:#&KD?8G4E47. . ...,.pzc..w8=1. T.#..\...... ------------------------------60b7133771dd--

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/filetransfer" -d "action=sendFileData&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&subject=SUBJECT_MESSAGE&contentType=CONTENT_TYPE&filename=FILE_NAME&data=FILE_DATA_BASE64"

- SUBJECT_MESSAGE: message subject
- CONTENT_TYPE: this value indicates the media type of the message content (example: image/jpeg, text/plain...).
- FILE_NAME: it is the name used to identify the file.
- FILE_DATA_BASE64: data base64 to file.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.tails">>> Dashboard >> API Access Details.

It accepts a file transfer.

HTTP POST https://{serverRoot}/filetransfer

Body:
- username: identifier of the user who wants to send a file.
- token: authentication token string.
- sessionId: session identifier in which we want to accept the file transfer.
- action: acceptFileTransferInvitation

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/filetransfer HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=acceptFileTransferInvitation&username=USERNAME&token=TOKEN&&sessionId=SESSION_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/filetransfer" -d "action=acceptFileTransferInvitation&username=USERNAME&token=TOKEN&sessionId=SESSION_ID"

- SESSION_ID: the value of this parameter is obtained from the notification channel.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.tails">>> Dashboard >> API Access Details.

Depending the state of the session, this call will decline/cancel the chat session. Decline is used to reject a file transfer invitation (a SIP DECLINE response will be sent to the originator of the session).

HTTP POST https://{serverRoot}/filetransfer

Body:
- username: identifier of the user who wants to decline a file.
- token: authentication token string.
- sessionId: session identifier in which we want to decline the file transfer.
- action: declineFileTransferInvitation

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/filetransfer HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=declineFileTransferInvitation&username=USERNAME&token=TOKEN&sessionId=SESSION_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/filetransfer" -d "action=declineFileTransferInvitation&username=USERNAME&token=TOKEN&sessionId=SESSION_ID"

- SESSION_ID: the value of this parameter is obtained from the notification channel.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.tails">>> Dashboard >> API Access Details.

Depending the state of the session, this call will decline/cancel the chat session. Cancel is used by the originator of the session to stop a file transfer invitation when it is not accepted (a SIP CANCEL request will be sent to the remote user).

HTTP POST https://{serverRoot}/filetransfer

Body:
- username: identifier of the user who wants to cancel a file.
- token: authentication token string.
- sessionId: session identifier in which we want to cancel the file transfer.
- action: cancelFileTransfer

Response: 200 status, response contains a result code: information about success/failure of action

HTTP Example:

POST /SERVER_ROOT/filetransfer HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=cancelFileTransfer&username=USERNAME&token=TOKEN&sessionId=SESSION_ID

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/filetransfer" -d "action=cancelFileTransfer&username=USERNAME&token=TOKEN&sessionId=SESSION_ID"

- SESSION_ID: the value of this parameter is obtained from the notification channel.


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME and TOKEN you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.tails">>> Dashboard >> API Access Details.

This notification group is related with the file exchange.

File sent:
The fileSent notification will be sent when the virtual client receives a file.
Parameters:
* username: the identifier of the sender identifier.
* contactId: the URI identifier of the user that receives the file.
* sessionId: identifier of the current file transfer session.

File received:
The fileReceived notification will be sent when the virtual client receives a file.
Parameters:
* username: the identifier of the user that receives the file.
* contactId: the URI of the sender identifier.
* sessionId: identifier of the current file transfer session.
* fileUrl: the URL where the file is located.
* fileName: the name of the file received.
* contentType: the file's content type.

File Transfer Invitation Received:
The fileTransferInvitationReceived notification will be sent when the client receives a file sent by the virtual client.
Parameters:
* username: the identifier of the user that receives the invitation.
* contactId: the URI of the sender identifier.
* sessionId: the identifier of the session of the invitation received.
* filesize: the size of the file received.
* fileName: the name of the file received.

File Transfer Invitation Error:
The fileTransferInvitationError notification will be sent when a file transfer invitation has not succeeded.
Parameters:
* username: the identifier of the sender identifier.
* contactId: the URI of the contact that has received the invitation.
* sessionId: the identifier of the session of the invitation received.

File Transfer Invitation Success:
The fileTransferInvitationSuccess notification will be sent when a file transfer invitation has succeeded.
Parameters:
* username: the identifier of the sender identifier.
* contactId: the URI of the contact that has received the invitation.
* sessionId: the identifier of the session of the invitation received.

File Session Closed Success:
The fileSessionClosed notification will be sent when a file transfer session succeed and it is closed.
Parameters:
* username: the identifier of the sender identifier.
* contactId: the URI of the contact that has received the invitation.
* sessionId: the identifier of the session of the invitation received.

This method is used to send geolocation.

HTTP POST https://{serverRoot}/chat

Body:
- username: identifier of the user who wants to send geolocation.
- token: authentication token string.
- contactId: uri (sip or tel) identifying the destination user.
- lat: latitude.
- lon: longitude.

Response: 200 status, response contains a result code: information about success/failure of action.

HTTP Example:

POST /SERVER_ROOT/chat HTTP/1.1 Accept: */* app_id:APP_ID app_key:APP_KEY Content-Type: application/x-www-form-urlencoded action=sendGeoLocationAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID& lat=40.3845391&lon=-3.7646069

CURL Example:
curl -H "app_id:APP_ID" -H "app_key:APP_KEY" -v -k -X POST "https://SERVER_ROOT/chat" -d "action=sendGeoLocationAutomaticSession&username=USERNAME&token=TOKEN&contactId=CONTACT_ID&lat=LAT&lon=LON"

- LAT: latitude
- LON: longitude


Note!!!: To know the values of APP_ID, APP_KEY, SERVER_ROOT, USERNAME, TOKEN and CONTACT_ID, you need sign up and then sign in the API portal. Once in your account, you can access the values of these parameters in >> Dashboard >> API Access Details.

This notification group is related to events for geolocation.

Geolocation received:
The geoLocationReceived notification will be sent when the virtual client receives a geolocation.
Parameters:
* username: the identifier of the user that receives the geolocation.
* contactId: the URI of the user sending the geolocation.
* sessionId: identifier of the current session.
* lat: latitude.
* lon: longitude.