Messaging Events

Overview

Purpose: To provide users access to the messaging data. The data in this API is based on a nested data model:

Messaging Event
- The core data model representing a messaging event linked to a specific recipient and from a specific source (e.g., Conditional Alert).
Message
- 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 API Authentication.

Base URL

https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/

Supported versions v1

Permissions Required: Edit Data

Filters

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

Filter Parameters
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 API response). See Pagination
date.lt (less than)	Filter events before a specific date	event.date	`date.lt=2021-05-01`
date.lte (less than or equal to)	Filter events on or before a specific date	event.date	`date.lte=2021-05-01`
date.gt (greater than)	Filter events after a specific date	event.date	`date.gt=2021-05-01`
date.gte (greater than or equal to)	Filter events on or after a specific date	event.date	`date.gte=2021-05-01`
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)	event.source	`source=broadcast`
status	Filter on the status of the event (e.g. error, completed, email-sent )	event.status	`status=error`
error_code	Filter on the event error code (e.g. NO_PHONE_NUMBER, NO_RECIPIENT, NO_MESSAGE-sent )	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 address	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.

Sorting Parameters
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)

Pagination

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/messaging-event/v1/?content_type=sms

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

# Request for next page
https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?cursor=XYZ

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

# Request for next page
https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?cursor=ABC

{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": null}}

# "meta.next" is null so there is no more data.

Request & Response Details

Sample Output

{
  "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/messaging-event/v1/?cursor=ZGF0ZS5ndGU9MjAyMC0wNS0xN1QyMCUzQTM3JTNBMTEuNzU3OTQwJmxhc3Rfb2JqZWN0X2lkPTEwMjUwOTYw"
  }
}

Sample API Calls

Sample Format

https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?[FILTER-NAME]=[FILTER-VALUE]

Example of a single filter:
- Example filter shown: date.gte=2020-07-13T06:30:21.109409

https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?date.gte=2020-07-13T06:30:21.109409

Example of multiple filters:
- Example filters shown: content_type=sms and phone_number=1234567

https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?content_type=sms&phone_number=1234567

API Fields and Data Structure

**API Fields**
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. 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 is related to one.
status	Status of this event (e.g. error, completed, in_progress)

**Source (Nested Object)**
Field	Note
type	Source type (e.g. broadcast, keyword)
source_id	ID of the source
name	Name of keyword, broadcast, etc.

**Recipient (Nested Object)**
Field	Note
type	Recipient type (web_user, case, or mobile_user)
recipient_id	Case ID / User ID
name	Case name / User name

**Form (Nested Object)**
Field	Note
app_id	Application ID
form_definition_id	Form Definition ID
form_name	Name of the form
form_submission_id	ID of the submitted form in the case of SMS surveys

**Error (Nested Object)**
Field	Note
code	Error code
message	Display text for the error code
message_detail	Additional detail about the error

**Messages (List of Nested Objects)**
Field	Note
message_id	ID of the message
type	“sms” or “email”
direction	“incoming” or “outgoing”
content	Actual message content that was sent or received
date	Message date
date_modified	Date of the last modification to the message
status	Message status (e.g. error, queued, received, sent)
backend	Name of the messaging backend gateway through which the message was sent/received (e.g. Twilio)
error_message	Error message in the case of an error
phone_number	(only for SMS)
email_address	(only for email)