Popular Help Content

No popular content.

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 CommCare's API Authentication Documentation.

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.

NameDescriptionFilters OnExample
limit

Number of records to return

Defaults to 20, maximum 5000


limit=100
cursorUsed 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 typesource=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_codeerror_code=NO_MESSAGE
phone_numberFilter on the recipient phone numberevent.message.phone_number
email_addressFilter on the recipient email addresevent.message.email_address
case_idFilter on the event case IDevent.case_id

Sorting

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

Sort ParameterDescription
order_by=dateOrder data by event.date (ascending)
order_by=-dateOrder data by event.date (descending)
order_by=date_last_activityOrder data by event.date_last_activity (ascending)
order_by=-date_last_activityOrder 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/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

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_typeType of the event e.g. sms, email, sms_survey
case_idID of the case if this event related to one
statusStatus of this event e.g. error, completed, in_progress

source (nested object)

type

Source type e.g.broadcast, keyword

source_id

ID of the source

name

Name of keyword, broadcast, etc

recipient (nested object)

type

Recipient type: web_user, case or mobile_user

recipient_id

Case ID / User ID

name

Case name / user name

form (nested object)

app_id


form_definition_id


form_name


form_submission_id**

ID of the submitted form in the case of SMS surveys

error (nested object)

code

error_code

message

Display text for code

message_detail

Additional detail about the error

messages (list of nested objects)

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)




  • No labels