Get SMS Chats API
MedChat offers the Get smsChats endpoint that allows you to get your organization's SMS chats (text messages) programmatically. Please see the API Reference here.
Quick Start
Before you get started, please visit the API Authentication page to get your org ID and access token as you'll need these to call into the endpoint.
Important: Access Token to use for Get SMS Chats
For downloading your SMS Chats, make sure to use a Token that includes read.sms_chats in its scope of access (see screenshot below).
The Get SMS Chats endpoint, like Get Chat endpoints for live chat, supports a constrained set of OData expressions.
For example, if you wanted to retrieve SMS chats initiated on or after Oct. 25, 2022, 9PM UTC, your query would use the ge (greater than or equal to) operator and look like this:
https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$filter=CreatedDateTime ge 2022-10-25T21:00:00Z
Here's a sample of get SMS chats request in curl syntax:
curl -X GET \ 'https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$filter=CreatedDateTime%20ge%202022-10-25T21:00:00Z' \ -H 'accept: application/vnd.medchat+json;v=1.0' \ -H 'authorization: Bearer {your_access_token}'
Date and Time
All dates and times are in UTC. So, when filtering data by a date/time field, you will want to covert any local times to UTC first. In addition, all returned results are in UTC as well. If you wish to display the date/time for a given timezone, you will need to covert the date/time to that local timezone.
OData Expressions
OData is a protocol that uses querystring parameters to shape the results of an API call to retrieve data.
Each OData querystring parameter is prefixed with $.
While the OData protocol encompasses more than what is supported by the MedChat endpoints, the following OData expressions are supported:
$filter
Use the $filter parameter to filter the results according to the provided condition(s).
| Operator | Name | Example |
|---|---|---|
| gt | Greater than | $filter=CreatedDateTime gt 2022-10-25T12:00:00Z |
| ge | Greater than or equal to | $filter=CreatedDateTime ge 2022-10-25T12:00:00Z |
| lt | Less than | $filter=CreatedDateTime lt 2022-10-25T12:00:00Z |
| le | Less than or equal to | $filter=CreatedDateTime le 2022-10-25T12:00:00Z |
| eq | Equals | $filter=userphonenumber eq '1234560000' |
| ne | Not equals | $filter=userphonenumber ne '1234560000 |
| and | And | $filter=CreatedDateTime ge 2022-10-25T12:00:00Z and CreatedDateTime le 2022-10-26T12:00:00Z |
| or | Or | $filter=Status eq 'Subscribed' or Status eq 'Active' |
| startswith(PropertyName, 'string') | Starts with | $filter=startswith(name, 'Jane') |
| endswith(PropertyName, 'string') | Ends with | $filter=endswith(name, 'Smith') |
Example:
Get the SMS chats with a status of "Active" or "Subscribed" on Oct. 25, 2022 UTC:
https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$filter=CreatedDateTime ge 2022-10-25T00:00:00Z and CreatedDateTime lt 2022-10-26T00:00:00Z and (status eq 'Subscribed' or Status eq 'Ended')
$expand
Use the $expand parameter to expand a child object or collection under the top-level SMS chat.
Expandable objects and collections under SMS chats:
- Messages
- Memberships
- TextBotExecutions
Example:
Get an SMS chat by ID and include the chat's Messages and Memberships:
https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$expand=Messages,Memberships
$orderby
Use the $orderby parameter to sort the results.
Follow your order by property name with desc to sort in descending order.
Example:
Get the SMS chats on Oct. 25, 2022 UTC, ordered by CreatedDateTime. descending:
https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$filter=CreatedDateTime ge 2022-10-25T00:00:00Z and CreatedDateTime lt 2022-10-26T00:00:00Z&$orderby=CreatedDateTime desc
$top
Use the $top parameter to limit the results returned to the top X SMS chats.
Example:
Get the last 10 SMS chats:
https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$orderby=CreatedDateTime desc&$top=10
$skip
Use the $skip parameter to exclude the first X SMS chats from the results.
Example:
Get SMS chats 21 through 30 from Oct. 25, 2022:
https://medchatapp.com/smschatapi/external/orgs/{your_org_Id}/smsChats?$filter=CreatedDateTime ge 2022-10-25T00:00:00Z&$orderby=CreatedDateTime&$top=20&$skip=10
Updated over 1 year ago