Get Chats API
MedChat offers a few endpoints that allow you to get your organization's chats programmatically.
- Use the Get chats endpoint to retrieve multiple chats.
- Use the Get chat by ID endpoint to retrieve a single chat.
Quick Start
Both get chat endpoints above support a constrained set of OData expressions.
For example, if you wanted to retrieve 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://api.medchatapp.com/orgs/{your_org_id}/chats?$filter=CreatedDateTime ge 2022-10-25T21:00:00Z
We'll dig a bit deeper into the supported OData functionality below, but for now, let's look our example get chats request in curl syntax:
curl -X GET \ 'https://api.medchatapp.com/orgs/{your_org_id}/chats?$filter=CreatedDateTime%20ge%202022-10-25T21:00:00Z' \ -H 'accept: application/vnd.medchat+json;v=1.0' \ -H 'authorization: Bearer {your_access_token}'
Visit the API Authentication page to get your org ID and 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=EndReason eq 'EndedByUser' |
| ne | Not equals | $filter=EndReason ne 'EndedByUser' |
| and | And | $filter=CreatedDateTime ge 2022-10-25T12:00:00Z and CreatedDateTime le 2022-10-26T12:00:00Z |
| or | Or | $filter=Status eq 'Archived' or Status eq 'Ended' |
| startswith(PropertyName, 'string') | Starts with | $filter=startswith(Name, 'Paul') |
| endswith(PropertyName, 'string') | Ends with | $filter=endswith(Name, 'Smith') |
Example:
Get the chats with a status of "Archived" or "Ended" on Oct. 25, 2022 UTC:
https://api.medchatapp.com/orgs/{your_org_id}/chats?$filter=CreatedDateTime ge 2022-10-25T00:00:00Z and CreatedDateTime lt 2022-10-26T00:00:00Z and (Status eq 'Archived' or Status eq 'Ended')
$expand
Use the $expand parameter to expand a child object or collection under the top-level chat.
Expandable objects and collections under chat:
- Members
- Messages
- PostChatSurvey
- Notes
Example:
Get a chat by ID and include the chat's Messages and Notes:
https://api.medchatapp.com/orgs/{your_org_id}/chats/{chat_id}?$expand=Messages,Notes
$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 chats on Oct. 25, 2022 UTC, ordered by CreatedDateTime. descending:
https://api.medchatapp.com/orgs/{your_org_id}/chats?$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 chats.
Example:
Get the last 10 chats:
https://api.medchatapp.com/orgs/{your_org_id}/chats/{chat_id}?$orderby=CreatedDateTime desc&$top=10
$skip
Use the $skip parameter to exclude the first X chats from the results.
Example:
Get chats 21 through 30 from Oct. 25, 2022:
https://api.medchatapp.com/orgs/{your_org_id}/chats/{chat_id}?$filter=CreatedDateTime ge 2022-10-25T00:00:00Z&$orderby=CreatedDateTime&$top=20&$skip=10
Updated almost 2 years ago