This Messaging API provides a mechanism to send text messages and files to Ringotel users from a third-party web service or application, as well as receive messages and notifications to the specified webhook.
\nThis Messaging API uses JSON as its communication format. You can use HTTP as a transport protocol. The server is listening to the HTTP requests over the SSL/TLS protocol on the 443 port.
\nUse API Key generated in your Ringotel Shell admin portal as a Bearer token to authenticate requests on the server.
\nAll API calls should be made to the admin portal URL:
\nhttps://shell.ringotel.co/api
The requests format includes method and params fields.
The successful response from the server includes the result object. In case of error, the error object will be returned.
Request:
\n{“method”: “getChatUsers”, “params”: { \"orgid\":\"16029670196176812345\" }}
Response:
\n{ “result”: [ { \"phone\": \"9001\", \"name\": \"9001\", \"id\": \"16266023844241412565\", \"state\": 2 }, { \"phone\": \"9002\", \"name\": \"9002\", \"id\": \"16271184912873588819\", \"state\": 2 }, ]}
Ringotel's APIs are not intended for code learning, and our support team does not have the ability for code mentoring. Using the Ringotel API means that the developer has at least a basic understanding of the HTTP protocol and the coding skills to implement API integration using the programming language of their choice.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"3136743","collectionId":"29f463dc-2310-43fa-9734-a9a2d43b4a7a","publishedId":"U16bvofV","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-08-30T06:14:50.000Z"},"item":[{"name":"Webhook Notifications","item":[{"name":"Text Message","id":"6c23dd3e-049d-4ecc-beb1-5c529de473b8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\t\"method\":\"message\",\n\t\"params\":{\n\t\t\"to\": \"1234567890\",\n\t\t\"from\": \"502\",\n\t\t\"orgid\": \"16287540703457500320\",\n\t\t\"userid\": \"16287541154521992797\",\n\t\t\"messageid\": \"1630253837469-a887a7c51d060d078a\",\n\t \"sessionid\": \"1630253837483-3fb8b0b9c7e935684a\",\n\t\t\"content\":\"Hello World!\",\n\t\t\"type\": 1\n\t},\n\t\"api_key\": \"Provide parameter senderid instead of to where applicable.
\"type\": 1 - text message
\"type\": 2 - file
To receive messages and notifications from the Ringotel platform, provide webhook parameter when creating an API Key. To authenticate requests coming to your webhook, map the api_key parameter that is included in the body of each request with the Ringotel API Key created in your Ringotel account.
You web server can receive the following notifications:
\n\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"3038250e-7098-4ab9-9661-8af20d77f823","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"ec2e17cd-355b-4058-9e2a-484306f6a5ca","type":"text/javascript","exec":[""]}}],"_postman_id":"700489e7-1587-4873-90ac-12a782627f95"},{"name":"API Methods","item":[{"name":"Get a list of users","id":"1ea4c228-2944-46a0-8f95-24201cdcfd4c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"method\": \"getChatUsers\",\n \"params\": {\n \"orgid\": \"16287540703457500320\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://shell.ringotel.co/api","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Sends a message to a Ringotel user via the Ringotel Messaging API.
\nThis request uses Bearer Token authentication. Include a valid Ringotel API Key in the Authorization header:
Authorization: Bearer <token>\n\nThe request body must be sent as JSON (Content-Type: application/json).
{\n \"method\": \"message\",\n \"params\": {\n \"orgid\": \"16648054657987889107\",\n \"from\": \"101\",\n \"to\": \"1234567890\",\n \"content\": \"Hi there 👋\"\n }\n}\n\nUse these API methods to send messages and files to the Ringotel users.
\n","_postman_id":"2bf779a0-2d74-4dc8-a009-5c996f3fe474","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"To sync a message with a specific chat session, please use the standard “message“ method with the sessionid parameter:
{\n \"method\": \"message\",\n \"params\":{\n \"from\": \"9003\",\n \"to\": \"234567668\",\n \"content\": \"Hello\",\n \"orgid\": \"17076444409917912922\",\n \"sessionid\": \"1710004869211-d3103a34bd2ce6023a\",\n \"timestamp\": 1770118887507\n }\n}\n\n{\n \"result\": {\n \"messageid\": \"1710100373597-8b065154afbbddfb96\"\n }\n}\n\nsessionid refers to the existing chat session, which you receive as a response from the API server once a chat has been created.
A new “sessionid“ will be returned if a message is sent to a session which is already closed.
\nIn addition, you can implicitly create a chat session for other users (if you need to sync messages with the users who don't have a chat session with an external number yet) by sending a message method without the content and sessionid parameters. Specify the external contact number in the from parameter and user’s extension number (for whom a chat session will be created) or an SMS number (DID) added via SMS integration in the to field:
{\n \"method\": \"message\",\n \"params\":{\n \"from\": \"234567668\",\n \"to\": \"9004\",\n \"orgid\": \"17076444409917912922\"\n }\n}\n\n{\n \"result\": {\n \"sessionid\": \"1710098613465-02d8b0a8b078cf73e5\"\n }\n}\n\nNow you can use the provided 'sessionid' in the follow-up API request to sync the message with the user's chat session:
\n{\n \"method\": \"message\",\n \"params\":{\n \"from\": \"9003\",\n \"to\": \"234567668\",\n \"content\": \"Hello\",\n \"orgid\": \"17076444409917912922\",\n \"sessionid\": \"1710098613465-02d8b0a8b078cf73e5\"\n }\n}\n\nAlternatively, instead of content you can specify the messageid parameter, which is particularly useful for syncing files:
{\n \"method\": \"message\",\n \"params\":{\n \"from\": \"9003\",\n \"to\": \"234567668\",\n \"orgid\": \"17076444409917912922\",\n \"messageid\": \"1710100665847-a1f4a223ffd202a9ea\",\n \"sessionid\": \"1710098613465-02d8b0a8b078cf73e5\"\n }\n}\n\n