Skip to content

List messages

get
https://api.reach.talkylabs.com/rest/messaging/v1/list

This operation allows to retrieve from the Reach platform message records that satisfied specified criteria.

When getting the message record list, results will be sorted on the dateCreated field with the most recent message records appearing first.

Pagination

The Reach platform uses offset-based pagination to list objects.

For instance, if a search request has a result of 100 objects with pageSize = 10 and page = 5, then objects with indices 51 through 60 are returned.

The client libraries introduces the limit parameter which can be used to indicate the maximum number of objects statisfying the specified criteria to return.

Parameters

  • deststringoptional

    Retrieve only messages sent to this phone number. The phone number should be in the E.164 format.

  • srcstringoptional

    Retrieve only messages sent from this phone number, in E.164 format, or this alphanumeric sender ID.

  • bulkIdentifierstringoptional

    Retrieve only messages that are assocaited with this bulkIdentifier.

  • sentAtdate-timeoptional

    Retrieve only messages sent at the specified date. Must be in ISO 8601 format.

  • sentAfterdate-timeoptional

    Retrieve only messages sent after the specified datetime. Must be in ISO 8601 format.

  • sentBeforedate-timeoptional

    Retrieve only messages sent before the specified datetime. Must be in ISO 8601 format.

  • pageSizeintegeroptional

    Maximum number of records to return per call. The default value is 20.

  • pageintegeroptional

    This is the page of message to be returned. This is to avoid returning duplicate data. The default value is 0.

Example 1: Retrieve the last 20 messages

curl -X GET https://api.reach.talkylabs.com/rest/messaging/v1/list?pageSize=20 -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "page": 0,
  "pageSize": 1,
  "totalMessages": 5,
  "totalPages": 5,
  "outOfPageRange": false,
  "messages": [
    {
      "appletId": "AIDXXXXXXXXXXXX",
      "apiVersion": "1.0.0",
      "body": "Hello World! This is a sms message.",
      "dest": "+237671234567",
      "src": "+237691234567",
      "bulkId": "myBulkGroup",
      "numSegments": 1,
      "numMedia": 0,
      "price": 25.0,
      "priceUnit": "xaf",
      "messageId": "MIDXXXXXXXXXXXX",
      "status": "sent",
      "messageType": "outbound",
      "errorCode": null,
      "errorMessage": null,
      "dateCreated": "2016-08-29T09:12:33.001Z",
      "dateSent": "2016-08-29T09:12:34.001Z",
      "dateUpdated": "2016-08-29T09:12:35.001Z"
    }
  ]
}

Example 2: Retrieve all messages matching some criteria

In this example, we retrieve all the messages sent on August 29, 2016 from +237691234567.

curl -X GET https://api.reach.talkylabs.com/rest/messaging/v1/list?sentAt=2016-08-29T00%3A00%3A00Z&src=%2B237691234567&pageSize=20 -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "page": 0,
  "pageSize": 1,
  "totalMessages": 5,
  "totalPages": 5,
  "outOfPageRange": false,
  "messages": [
    {
      "appletId": "AIDXXXXXXXXXXXX",
      "apiVersion": "1.0.0",
      "body": "Hello World! This is a sms message.",
      "dest": "+237671234567",
      "src": "+237691234567",
      "bulkId": "myBulkGroup",
      "numSegments": 1,
      "numMedia": 0,
      "price": 25.0,
      "priceUnit": "xaf",
      "messageId": "MIDXXXXXXXXXXXX",
      "status": "sent",
      "messageType": "outbound",
      "errorCode": null,
      "errorMessage": null,
      "dateCreated": "2016-08-29T09:12:33.001Z",
      "dateSent": "2016-08-29T09:12:34.001Z",
      "dateUpdated": "2016-08-29T09:12:35.001Z"
    }
  ]
}

Example 3: Retrieve all messages sent within a specific time period

In this example, we retrieve all the messages sent before August 31, 2016 but after August 21, 2016.

curl -X GET https://api.reach.talkylabs.com/rest/messaging/v1/list?sentAfter=2016-08-21T00%3A00%3A00Z&sentBefore=2016-08-31T00%3A00%3A00Z&pageSize=20 -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "page": 0,
  "pageSize": 1,
  "totalMessages": 5,
  "totalPages": 5,
  "outOfPageRange": false,
  "messages": [
    {
      "appletId": "AIDXXXXXXXXXXXX",
      "apiVersion": "1.0.0",
      "body": "Hello World! This is a sms message.",
      "dest": "+237671234567",
      "src": "+237691234567",
      "bulkId": "myBulkGroup",
      "numSegments": 1,
      "numMedia": 0,
      "price": 25.0,
      "priceUnit": "xaf",
      "messageId": "MIDXXXXXXXXXXXX",
      "status": "sent",
      "messageType": "outbound",
      "errorCode": null,
      "errorMessage": null,
      "dateCreated": "2016-08-29T09:12:33.001Z",
      "dateSent": "2016-08-29T09:12:34.001Z",
      "dateUpdated": "2016-08-29T09:12:35.001Z"
    }
  ]
}