Messaging Events

Summary

To provide users access to the messaging data.

The data in this API is based around a nested data mode:

Messaging Event
- This is the core data model for the API and represents a messaging event linked to a specific recipient and from a specific source e.g. Conditional Alert
Message
- This is the actual message that went to the user
- A single event may have multiple messages e.g. SMS surveys which will have one message per interaction with the recipient.

Authentication: For more information, please review https://dimagi.atlassian.net/wiki/x/LwXKfw.

Base URL: https://www.commcarehq.org/a/[domain]/api/[version]/mesaging-event/

Supported versions: v0.5

Filters

These are the filter parameters that the API call can use. Examples of how to use the filters in an API call appear below.

Name	Description	Filters On	Example

Name

Description

Filters On

Example

limit

Number of records to return

Defaults to 20, maximum 5000

limit=100

cursor

Used for pagination. Value provided in the API response. See Pagination.

date.lt (less than)

date.lte

(less than or equal to) date.gt (greater than) date.gte (greater than or equal to)	Accepts ISO 8601 formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS e.g. 2020-07-14, 2020-07-13T06:53:38.059518 If the timestamp portion of the filter is omitted for the `.lte` or `.gte` filters the results will include all events on that date.	event.date	date.lt=2021-05-01 (before a date) date.lte=2021-05-01 (on or before a date) date.gt=2021-05-01 (after a date) date.gte=2021-05-01 (on or after a date)
date_last_activity.lt date_last_activity.lte date_last_activity.gt date_last_activity.gte	Date filter against `date_last_activity` Accepts ISO 8601 formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS e.g. 2020-07-14, 2020-07-13T06:53:38.059518 If the timestamp portion of the filter is omitted for the `.lte` or `.gte` filters the results will include all events on that date.	event.date_last_activity Date of last update related to this event.
content_type	Filter on the content type of the event e.g. sms sms-survey email manual-sms api-sms chat-sms	event content_type	content_type=sms
source	Filter on the source of the event e.g. broadcast (includes scheduled-broadcast, immediate-broadcast) scheduled-broadcast immediate-broadcast keyword reminder conditional-alert	source type	source=broadcast
status	Filter on the status of the event e.g. error completed email-sent	event.status message.status	status=error
error_code	Filter on the event error code e.g. NO_PHONE_NUMBER NO_RECIPIENT NO_MESSAGE	event.error_code	error_code=NO_MESSAGE
phone_number	Filter on the recipient phone number	event.message.phone_number
email_address	Filter on the recipient email addres	event.message.email_address
case_id	Filter on the event case ID	event.case_id

Sorting

These sorting parameters can be applied to the existing search results alongside the filters.

Sort Parameter	Description

Sort Parameter	Description
order_by=date	Order data by event.date (ascending)
order_by=-date	Order data by event.date (descending)
order_by=date_last_activity	Order data by event.date_last_activity (ascending)
order_by=-date_last_activity	Order data by event.date_last_activity (descending)

This API makes use of cursor pagination. Each request will include a "meta.next" field which will contain a URL that can be used to fetch the next page of data. This URL includes all the filters that were supplied with the original request and should be used without modification.

If "meta.next" is 'null' it means there is no more data.

Example:

# First request

https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?content_type=sms

	{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": "https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?cursor=XYZ}}


####
# Request for next page

https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?cursor=XYZ

	{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": "https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?cursor=ABC}}


####
# Request for next page

https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?cursor=ABC

	{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": null}}
	
	# "meta.next" is null so there is no more data

Sample Output

JSON Format

API Results
{
  "objects": [
    {
      "id": 10215869,
      "content_type": "email",
      "date": "2020-05-15T04:11:27.482899",
      "date_last_activity": "2020-05-15T04:11:27.482899",
      "case_id": "523132e0-a562-4be1-bbc8-a634423c5c0c",
      "domain": "ny-dev-cdcms",
      "error": null,
      "form": null,
      "messages": [
        {
          "message_id": 153444,
          "date": "2021-04-13T21:25:26.989",
          "date_modified": null,
          "type": "sms",
          "direction": "outgoing",
          "content": "Welcome to CommCare",
          "status": "sent",
          "backend": "MOBILE_BACKEND_TWILIO",
          "phone_number": "+15555993494"
        },
	  ],
      "recipient": {
        "recipient_id": "523132e0-a562-4be1-bbc8-a634423c5c0c",
        "type": "case",
        "name": "Mary Little"
      },
      "source": {
        "source_id": "4654",
        "type": "conditional-alert",
        "name": "Email - Welcome Packet"
      },
      "status": "completed"
    },
    ....
  ],
  "meta": {
    "limit": 20,
    "next": "https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?cursor=ZGF0ZS5ndGU9MjAyMC0wNS0xN1QyMCUzQTM3JTNBMTEuNzU3OTQwJmxhc3Rfb2JqZWN0X2lkPTEwMjUwOTYw"
  }
}

Sample APIs

https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?[FILTER-NAME]=[FILTER-VALUE]
Example of single filter:
- https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?date.gte=2020-07-13T06:30:21.109409
  - Example filter shown:
    - date.gte=2020-07-13T06:30:21.109409
Example of multiple filters:
- https://www.commcarehq.org/a/[domain]/api/v0.5/messaging-event/?content_type=sms&phone_number=1234567
  - Example filters shown:
    - content_type=sms
    - phone_number=1234567

API Fields and Data Structure

Field	Note

Field	Note
id	Event ID
date	Event Date e.g. 2020-07-13T06:30:21.136197
date_last_activity	Date of the last message activity for this event. This is useful for exports since the ‘date’ field is the date of creation.
domain	The Project Space this event belongs to.
content_type	Type of the event e.g. sms, email, sms_survey
case_id	ID of the case if this event related to one
status	Status of this event e.g. error, completed, in_progress
source (nested object)
recipient (nested object)
form (nested object)
error (nested object)
messages (list of nested objects)