Metrics
The following are the API metrics you can retrieve over Metrics API. You can specify metrics to fetch specific performance indicators such as total traffic count, click rates, delivery success rates, and more. They provide valuable insights to monitor and optimize your strategies effectively.
- Delivery
| Metrics name | API syntax | Description |
|---|---|---|
| Total traffic | TOTAL_TRAFFIC_COUNT | The total number of messages or message segments (parts) sent to your customers (outbound) and messages received from your customers (inbound). Channel specifics:
|
| Messaging interactions | INTERACTION_COUNT | Number of distinct messaging interactions. When combined with the TRAFFIC_TYPE dimension, it helps analyze messaging traffic in detail.This metric allows you to break down messaging interactions into different WhatsApp or RCS channel-specific categories, such as conversations or sessions and single or basic messages. |
| Total SMS messages | TOTAL_SMS_MESSAGES_COUNT | The total number of SMS messages sent to and received from customers (inbound and outbound). Messages split into multiple segments due to length are counted as a single distinct message. Channel specifics:
|
| Total sent | TOTAL_SENT_TRAFFIC_COUNT | The total number of messages submitted for delivery (outbound). Channel specifics:
|
| Delivered | DELIVERED_TRAFFIC_COUNT | The total number of messages delivered to a recipient. |
| Delivery rate | TRAFFIC_DELIVERY_RATE | The percentage of messages successfully delivered to recipients. |
| 5 sec delivery rate | TRAFFIC_DELIVERED_IN_5_SEC_RATE | The percentage of messages delivered within a 5-second time frame. |
- Inbound
| Metrics name | API syntax | Description |
|---|---|---|
| Received traffic | TOTAL_RECEIVED_TRAFFIC_COUNT | The total number of messages you received from customers (inbound). Channel specifics:
|
| Received to sent ratio | RECEIVED_TO_SENT_TRAFFIC_RATIO | Ratio of received (inbound) to sent (outbound) messages that were not rejected. Channel specifics:
|
- Delivery failure
| Metrics name | API syntax | Description |
|---|---|---|
| Failed | FAILED_TRAFFIC_COUNT | The total number of sent (outbound) messages not delivered to a recipient. Channel specifics:
|
| Bounced | TOTAL_BOUNCE_COUNT | The total number of emails not delivered to recipients, including soft bounces (temporary issue) and hard bounces (permanent issue). Channel specifics:
|
| Bounce rate | TOTAL_BOUNCE_RATE | The percentage of emails that were not delivered to recipients' inboxes. This includes both soft and hard bounces. It is calculated by summing up soft bounced and hard bounced messages, and dividing them by the number of messages sent (Total sent). Channel specifics:
|
| Dropped | TOTAL_DROPPED_COUNT | The submitted emails that were dropped before delivery due to various reasons, such as the recipient unsubscribed, address bounced, the message was marked as spam, or sender errors such as blocked or unverified domain, or content-related issues like expired templates or too many URLs. Channel specifics:
|
| Dropped rate | TOTAL_DROPPED_RATE | The percentage calculated by dividing the number of dropped emails by the number of accepted emails. Channel specifics:
|
| Suppressed | TOTAL_SUPPRESSED_COUNT | The number of emails that were not sent due to a bounce or a negative recipient reaction (marking the email as spam). Channel specifics:
|
| Soft bounced | SOFT_BOUNCE_COUNT | The number of emails temporarily undeliverable to recipients. This can happen due to the recipient's inbox being full, the domain temporarily unavailable, or the mailbox provider suspecting legitimacy or lack of recipient opt-in. Channel specifics:
|
| Soft bounced rate | SOFT_BOUNCE_RATE | The percentage of emails temporarily undeliverable to recipients. It is calculated by dividing the number of soft bounced messages by the number of messages sent (Total sent). Channel specifics:
|
| Hard bounced | HARD_BOUNCE_COUNT | The number of emails that received a permanent error from mailbox providers when attempting to deliver the email to a specific recipient. Channel specifics:
|
| Hard bounced rate | HARD_BOUNCE_RATE | The percentage of emails permanently undeliverable to recipients. It is calculated by dividing the number of hard bounced messages by the number of messages sent (Total sent). Channel specifics:
|
- Seen/Opened
| Metrics name | API syntax | Description |
|---|---|---|
| Seen/Unique opens | SEEN_OPENED_TRAFFIC_COUNT | The number of messages that were seen or opened by unique recipients, counting each recipient only once regardless of how many times they opened the same message. Consider that recipients can turn off their read receipts, which can result in a lower seen count. Channel specifics:
|
| Seen rate/Unique opens rate | SEEN_OPENED_TRAFFIC_RATE | The percentage of messages that were seen or opened by unique recipients. Consider that recipients can turn off their read receipts, which can result in a lower seen rate. Channel specifics:
|
| Opens | VIEWED_TOTAL_COUNT | The number of open messages per single email address. The emails opened multiple times by the same recipient are also counted. Channel specifics:
|
| Open rate | VIEWED_TOTAL_RATE | The percentage of recipients who opened an email campaign. Channel specifics:
|
- Clicks/Engagement
| Metrics name | API syntax | Description |
|---|---|---|
| Unique clicks | UNIQUE_CLICKS_COUNT | The number of unique recipients who clicked on any link within a message, counting each recipient only once regardless of the number of links clicked in that message. Channel specifics:
|
| Unique click-through rate | UNIQUE_CLICK_THROUGH_RATE | The percentage of unique recipients who clicked on a link compared to the total number of messages delivered, counting each recipient only once regardless of the number of links clicked in that message. Channel specifics:
|
| Unique clicked URLs | UNIQUE_URL_CLICK_COUNT | The number of unique URLs clicked in a single message. Channel specifics:
|
| Click-to-open rate (CTOR) | CLICK_TO_OPEN_RATE | The percentage of recipients counted as unique clicks divided by unique opens or seens (each recipient is counted only once regardless of the number of links clicked in that message). |
| Total clicks | TOTAL_CLICKS_COUNT | The total number of clicks on all URLs within a single message, including multiple clicks on the same link. For example, if a message contains 3 links and each link is clicked twice, the total clicks count is 6. Channel specifics:
|
| Click rate | TOTAL_CLICK_RATE | The percentage of recipients who clicked on any link, calculated as the total number of clicks across all URLs within a message divided by the total number of delivered messages. For instance, if 200 SMS messages are sent and there are 400 total clicks, the TOTAL_CLICK_RATE is 200%. |
- Feedback
| Metrics name | API syntax | Description |
|---|---|---|
| Unsubscribes | UNSUBSCRIBED_USER_COUNT | The number of recipients who unsubscribed (opted out) from future communications sent from the sending address. Channel specifics:
|
| Unsubscribe rate | UNSUBSCRIBED_USER_RATE | The percentage of recipients who unsubscribed (opted out) from future communications sent from the sending address. Channel specifics:
|
| Spam complaints | EMAIL_COMPLAINTS_COUNT | The number of emails that recipients reported as spam. Channel specifics:
|
| Spam complaints rate | EMAIL_COMPLAINTS_RATE | The percentage of emails that recipients reported as spam. Channel specifics:
|
Aggregation/Dimensions
You can view metrics in meaningful groupings. For example, total traffic counts become much more impactful when you view them for each sender, network, or country.
Our API provides extensive options (aggregateBy) for data aggregation, including grouping by time intervals, message status, and error types. This grouping functionality simplifies data analysis and aids in extracting meaningful insights from large datasets.
| Dimension name | Description |
|---|---|
ACCOUNT_KEY | Groups results by account key in the response, showing corresponding account key values. |
HOUR | Groups results by hour, showing corresponding timestamp values. |
DAY | Groups results by day, showing corresponding day values. |
WEEK_SATURDAY_START | Groups results by week starting from Saturday, showing corresponding timestamp values. |
WEEK_SUNDAY_START | Groups results by week starting from Sunday, showing corresponding timestamp values. |
WEEK_MONDAY_START | Groups results by week starting from Monday, showing corresponding timestamp values. |
MONTH | Groups results by month, showing corresponding month values. |
QUARTER | Groups results by quarter, showing corresponding quarter values. |
YEAR | Groups results by year, showing corresponding year values. |
TIME_TO_DELIVER | Groups results by 'time to deliver' period, showing corresponding 'time to deliver' period description value. |
TIME_TO_CLICK_FROM_SEEN | Groups results by the difference in time (sec) between a message click and seen events, showing the calculated values. |
TIME_TO_CLICK_FROM_DELIVERED | Groups results by the difference in time (sec) between a message click and delivered events, showing the calculated values. |
TIME_TO_SEEN_FROM_DELIVERED | Groups results by the difference in time (sec) between a message seen and delivered events, showing the calculated values. |
CHANNEL_CODE | Groups results by channel, showing corresponding channel code values. |
CHANNEL_NAME | Groups results by channel name, showing corresponding channel name values. |
DIRECTION | Groups results by the traffic direction, showing corresponding direction values: OUTBOUND for traffic sent to a client and INBOUND for traffic received from a client. |
TRAFFIC_TYPE | Groups results by traffic type, showing corresponding traffic type values. |
SENDER | Groups results by sender, showing corresponding sender values. |
SENDER_TYPE | Groups results by sender type, showing corresponding sender type values. |
SENDER_DOMAIN | Groups the results by sender domain showing corresponding sender domain values. |
RECIPIENT_DOMAIN | Groups the results by recipient domain showing corresponding recipient domain values. |
URL | Groups results by the initial URL from a message, showing corresponding URL values. Please note that you cannot use aggregateBy URL with the non-URL measures. UNIQUE_URL_CLICK_COUNT would be valid, while TOTAL_TRAFFIC_COUNT would NOT be valid. |
COMMUNICATION | Groups results by communication, showing corresponding communication ID value. |
CAMPAIGN_REFERENCE | Groups results by campaign reference, showing corresponding campaign reference ID value. |
NETWORK_ID | Groups results by network, showing corresponding network ID values. |
NETWORK_NAME | Groups results by network, showing corresponding network name values. |
COUNTRY_ID | Groups results by country, showing corresponding country ID values. |
COUNTRY_NAME | Groups results by country, showing corresponding country name values. |
APPLICATION_ID | Groups results by application, showing corresponding application ID values. |
ENTITY_ID | Groups results by entity, showing corresponding entity ID values. |
STATUS_GROUP | Groups results by status group, showing corresponding status group values of a response. |
STATUS | Groups results by status name, showing corresponding status values of a response. |
ERROR_GROUP | Groups results by error group, showing corresponding error group values of a response. |
ERROR_CODE | Groups results by error code, showing their corresponding error code values of a response. |
Forced Aggregation by CHANNEL_CODE:
- The
CHANNEL_CODEdimension is always included in the results, regardless of whether it is specified in theaggregateByparameter. This ensures the integrity and accuracy of the calculated metrics. For example, even if you request aggregation only byHOUR, the results will still include theCHANNEL_CODEdimension. - If neither
CHANNEL_CODEnorCHANNEL_NAMEis specified in the initial request, theCHANNEL_CODEdimension will be implicitly added to the results. - If you choose to aggregate by
CHANNEL_NAME, theCHANNEL_CODEwill not be added automatically. This allows clients the flexibility to have both values if needed.
Filters
Customize your queries with an array of filtering options to limit results by specific characteristics. With this flexibility, you can retrieve your data according to your specific requirements.
| Filter | API syntax | Description | Required |
|---|---|---|---|
| Accounts | accountKeys | Targets specific accounts based on accountKeys (opens in a new tab). Restrictions apply for legacy accounts. | No |
| Sub-accounts | includeSubaccounts | Includes subaccount traffic data for comprehensive analysis. | No |
| Sent time range | sentSinces | Includes a specific message time frame. | Yes |
sentUntil | |||
| Engagement timeframe | timeToDeliver | Represents the time within which a message is delivered using time buckets. For instance, you can filter only messages delivered within 1 second. The from bucket is inclusive, while the to bucket is exclusive. | No |
timeToClickFromSeen | Represents the time within which a URL is clicked after the message is seen using time buckets. For example, you can filter only messages whose URLs were clicked within 1 second after they were seen. The from bucket is inclusive, while the to bucket is exclusive. | ||
timeToClickFromDelivered | Represents the time within which a URL is clicked after the message is delivered using time buckets. For example, you can filter only messages whose URLs were clicked within 1 second after they were delivered. The from bucket is inclusive, while the to bucket is exclusive. | ||
timeToSeenFromDelivered | Represents the time within which a message is seen after the message is delivered using time buckets. For example, you can filter only messages that were seen within 1 second after they were delivered. The from bucket is inclusive, while the to bucket is exclusive. | ||
| Statuses and error codes | statusGroups | Filter by specific status or error codes.
| No |
statuses | |||
errorGroups | |||
errorCodes | |||
| Direction | direction | Categorizes traffic based on direction, distinguishing between outbound and inbound messages. | No |
| Channel | channelCode | Categorizes traffic based on communication channels. | Yes |
| Traffic type | trafficTypes | List of possible values for traffic types | No |
| Sender | senders | Filters traffic based on specific senders or sender types. List of possible values for sender types. | No |
| Sender type | senderTypes | No | |
| Communication ID | communicationIds | Categorizes traffic based on specific identifiers such as communication IDs. It is only applicable for traffic sent over Infobip SaaS solutions, such as Broadcast or Moments (Flow). | No |
| Campaign reference ID | campaignReferenceIds | Categorizes traffic based on specific identifiers such as campaign reference IDs. It is only applicable for traffic sent over Infobip APIs. | No |
| Network | networkIds | Categorizes traffic based on specific identifiers, such as network IDs, or country IDs. | No |
| Country | countryIds | No | |
| Application | applicationId | By including additional CPaaSX parameters like applicationId and entityId, you can get valuable insights into the source and purpose of your communication activities, aiding in more accurate analysis and decision-making. Use these parameters if you are using CPaaSX concepts and features. Learn more about CPaaSX here. | No |
| Entity | entityId | No |
Channels
The following is a list of available channels and services and their codes:
| Dimension name | Description |
|---|---|
| SMS | SMS |
| EMAILVALID | Email validation |
| FB | Facebook Messenger |
| IM | Instagram Messaging |
| KAKAOA | Kakao Alim |
| KAKAOC | Kakao Chingu |
| KAKAOS | Kakao Sangdam |
| LINELNS | LINE Official Notification |
| LINEOA | LINE Official Account |
| MMS | MMS |
| NL | Number lookup |
| RCS | RCS |
| TELEGRAM | Telegram |
| VIBER | Viber Business Messages |
| VIBERBOTS | Viber Bots |
| ZALONS | Zalo Notification Service |
| APPLECB | Apple Messages for Business |
trafficTypes
In messaging platforms like WhatsApp and RCS, traffic types categorize messaging interactions based on their nature and purpose, influencing how they are billed. For WhatsApp, traffic types include Marketing, Utility, Authentication, and Service Conversations, each with its distinct billing criteria. Meanwhile, RCS categorizes messages as Basic Transactions, Single Transactions, A2P Conversation or P2A Conversation. Understanding these traffic types is essential for businesses to efficiently handle their messaging operations. It helps interpret the INTERACTION_COUNT metric, specifically designed to analyze messaging traffic in detail.
| ID | Name | Description |
|---|---|---|
| 1 | UTILITY_CONVERSATION | WA Utility conversation |
| 2 | AUTHENTICATION_CONVERSATION | WA Authentication conversation |
| 3 | MARKETING_CONVERSATION | WA Marketing conversation |
| 4 | SERVICE_CONVERSATION | WA Service conversation |
| 5 | BASIC_TRANSACTION_BASED_MESSAGE | RCS basic transaction based message |
| 6 | SINGLE_TRANSACTION_BASED_MESSAGE | RCS single transaction based message |
| 7 | A2P_CONVERSATION | RCS A2P (Application-to-Person) conversation |
| 8 | P2A_CONVERSATION | RCS P2A (Person-to-Application) conversation |
senderTypes
The table below outlines various sender types available for messaging operations, each serving specific purposes and catering to different regions.
| ID | Name | Description |
|---|---|---|
| 1 | ALPHANUMERIC | Alphanumeric sender |
| 2 | SHORT_CODE | Short numbers |
| 3 | TOLL_FREE_NUMBERN | Toll free number (Limited to North America) |
| 4 | VIRTUAL_LONG_NUMBER | Virtual long number |
| 5 | 10DLC | 10DLC (Limited to North America) |
| 6 | DOMAIN | Used for Email |
Sender types for some channels like Viber BM or RCS are mapped to their channel value, as specific sender types are not relevant to them.