GetTransactionalWhatsappReport

get

https://api.dengage.com/rest/transactional/whatsapp

The GetTransactionalWhatsappReport function returns the send and event report of transactional WhatsApp messages. Both template messages sent with SendTransactionalWhatsapp (POST /transactional/whatsapp) and chat messages sent with SendChatMessage (POST /transactional/whatsapp/sendChatMessage) are included.

Required permission: transactionalWhatsapp.read

Query Modes

1. Single send lookup (transactionId)

transactionId is the value returned by the send endpoints.
When transactionId is provided, beginTime, endTime, gsm, tag, messageType and eventType are ignored and not validated. Date range rules do not apply.
At most one record is returned. If no send exists with this transactionId, result is empty.
limit and offset are still validated. Keep offset as 0, otherwise the result is empty.

2. List query (without transactionId)

beginTime and endTime are required.
endTime cannot be earlier than beginTime, and the range cannot be longer than 7 days.
Sends are filtered by their send time (createdAt). Both beginTime and endTime are inclusive.
beginTime and endTime are evaluated in your account's time zone, the same time zone as createdAt in the response.
gsm, tag, messageType and eventType are optional and can be combined. All provided filters are applied together (AND).

Filter Rules

Parameter	Rule
`gsm`	Exact match with the recipient number used in the send request. The number is stored as it was sent, so `+905xxxxxxxxx` and `905xxxxxxxxx` are different values. Use the same format you used while sending.
`tag`	Exact match (case-sensitive) with one of the tags given in the send request. A send with several tags is returned when any of its tags matches.
`messageType`	`TEMPLATE` or `CHAT` (case-insensitive). `TEMPLATE` returns template sends, `CHAT` returns chat message sends.
`eventType`	`DL`, `OP`, `BO` or `ER` (case-insensitive). Returns sends that have at least one event of this type, even if it is not the latest event. The `events` array of a returned send still contains all of its events.

Event Types

Code	Meaning
`DL`	Delivered to the recipient
`OP`	Read by the recipient
`BO`	Bounced, the message could not be delivered
`ER`	Error

Click and unsubscribe events are not reported for transactional WhatsApp messages.

Response Details

Each item in result is one send. Sends are ordered by createdAt, newest first.
eventType, eventDate and eventReason show the latest event of the send, which is its current status. They are null when no event has been received for the send yet.
events contains all events of the send, ordered from oldest to newest. It is an empty array when no event has been received yet.
eventReason contains the error detail when there is one, otherwise it is null.
messageType is TEMPLATE for template sends and CHAT for chat message sends.
templateName and templateId are null for chat message sends.
partnerId is the encrypted partner ID, in the same format as the partnerId used in the send request.
WhatsApp auto reply messages are not included in the report.

Paging

limit is the page size: between 100 and 1000, default 100.
offset is the number of sends to skip: 0 or greater, default 0.
queryForNextPage is true when there are more sends after this page. To get the next page, send the same request with offset increased by limit.
affectedRowCount is the number of sends in this page.
The total number of matching sends is not returned.

Errors

Only the first failing rule is returned. Validation errors return HTTP 400 with code 11:

Parameter	Rule	Error message
`beginTime`	Required when `transactionId` is not provided	`beginTime is required when transactionId is not provided`
`endTime`	Required when `transactionId` is not provided	`endTime is required when transactionId is not provided`
`endTime`	Cannot be earlier than `beginTime`	`endTime cannot be earlier than beginTime`
`beginTime` / `endTime`	Range cannot be longer than 7 days	`Time range cannot be greater than 7 days`
`limit`	Between 100 and 1000	`limit value must be between 100 and 1000`
`offset`	0 or greater	`offset value cannot be less than 0`
`messageType`	`TEMPLATE` or `CHAT`	`messageType must be one of: TEMPLATE, CHAT`
`eventType`	`DL`, `OP`, `BO` or `ER`	`eventType must be one of: DL, OP, BO, ER`
Any parameter	Value cannot be converted to its type (invalid uuid, date or number)	`Invalid parameter. Could not convert {Parameter}:{value} to {Type}.`

Other errors:

Too many concurrent requests: HTTP 400 with code 429.
Missing transactionalWhatsapp.read permission: HTTP 403 with code 10.
Unexpected server error: HTTP 500 with code 999.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

transactionId

uuid

The transactionId returned by the send endpoints. When provided, only this send is returned and beginTime, endTime, gsm, tag, messageType and eventType are ignored.

beginTime

string

Start of the send time (createdAt) range, inclusive. Required when transactionId is not provided; ignored when transactionId is provided. Evaluated in your account's time zone.

Format: yyyy-MM-ddTHH:mm:ss or yyyy-MM-dd HH:mm:ss

endTime

string

End of the send time (createdAt) range, inclusive. Cannot be earlier than beginTime, and the range cannot be longer than 7 days. Required when transactionId is not provided; ignored when transactionId is provided. Evaluated in your account's time zone.

Format: yyyy-MM-ddTHH:mm:ss or yyyy-MM-dd HH:mm:ss

gsm

string

Recipient phone number. Exact match with the number used in the send request (+905xxxxxxxxx and 905xxxxxxxxx are different values).

tag

string

Tag given in the send request. Exact, case-sensitive match.

messageType

string

enum

TEMPLATE for template sends, CHAT for chat message sends. Case-insensitive.

Allowed:

eventType

string

enum

Returns sends that have at least one event of this type. Case-insensitive.

Allowed:

limit

integer

100 to 1000

Defaults to 100

Page size

offset

integer

≥ 0

Defaults to 0

Number of sends to skip

Responses

401

Not authenticated. Please re-login.

200

400Validation error (code 11) or too many concurrent requests (code 429)

403The operation is not allowed. Your api user is not authorized to use this api.

500Unexpected error