Billing event reports and activity logs

This page describes the data files that RBM creates to assist carriers with billing and auditing.

File	Description	Who has access
Billing event report	Aggregated report of billable events between launched agents and users.	All carriers with a signed RBM MDA.
Activity log	Raw data log of RBM activity, including billable events.	Carriers with a signed RBM MDA who operate the Google RCS Service under their own Terms of Service (ToS).

File generation

Each data file represents one day of RBM usage in Coordinated Universal Time (UTC). Files are generated daily between 10:00 and 12:00 UTC.

• For non-conversational agents, the files contain data from the 24-hour period that immediately preceded the file generation time. For example, if a billing event report is generated at 11:00 UTC on May 5, it will contain data from 11:00 UTC on May 4 to 11:00 UTC on May 5.

• For conversational agents, the files contain data from the 24-hour period 1-2 days prior to the file generation time. For example, if a billing event report is generated at 11:00 UTC on May 5, it may contain data from 11:00 UTC on May 3 to 11:00 UTC on May 4.

  The reason for the delay is that RBM activity for conversational agents is linked to conversations, which can take up to 48 hours to complete. This delay allows RBM to capture all messages within a conversation before calculating the billing event. For more information about conversational agents, refer to Agent billing categories.

Key points:

• No activity: If there's no platform activity on a given day, no file is generated.

• Naming: The date in the filename is the file generation date, not the date of the data within.

• Retention: Files are stored for a maximum of 30 days before being deleted.

You can use these files to update your data warehouse with the latest platform usage metrics.

File storage and access

Data files are encrypted at rest and in transfer.

To retrieve data files by SFTP, provide your SFTP public key. To generate keys, see Generate a Secure Shell (SSH) key pair for an SFTP dropbox.

The SFTP server is partnerupload.google.com, and connection is on a high port number (19321) for additional security.

You can use the following command to access your data files:

sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

Google provides account usernames in the following formats:

• rbmreports-billableevents-<carrier name>
• rbmreports-activity-<carrier name>

Google specifies <carrier name> and provides separate account for each report type.

Separate accounts are provided for accessing the different report types.

File availability

If no data files have been generated yet, you'll see an SFTP error similar to remote readdir("/"): No such file or directory, which is expected.

A file won't be generated if there is no RBM traffic to report. This means there may be some days when no files are generated. If you need empty files to streamline your process, contact [e-mail].

Billing event reports

Billing event reports are records of billing events, which are calculated based on the agent's billing category and the type of messages it sends. Billing event reports are available to all carriers who have an RBM MDA in place.

Note: Billing event reports contain confidential information, but no user Personal Identifiable Information (PII), such as MSISDN, hashed MSISDN, or any user unique identifier.

Agent billing categories

When creating an agent, the owner sets its billing category based on how the agent will interact with users. The billing category does not restrict the number or type of messages an agent can send. But it does determine how the agent will be billed for messages. The two main billing categories are described in the following table.

Billing category	Agent type	Example use cases	Billing method
Non-conversational (Includes Basic Message and Single Message categories. Note: There is no longer any difference between these two categories. An agent in either category will be billed as a non-conversational agent.)	Agents that primarily send one-way messages.	OTPs Alerts Promotional offers	Billed for each message delivered to the user.
Conversational	Agents that are designed for back-and-forth exchanges with users.	Finding the right product Booking a ticket Troubleshooting an issue	Billed per conversation: If one party (the agent or user) replies to a message from the other party within 24 hours, a conversation starts. During the conversation window (24 hours after the first reply), the agent and user can exchange any number of messages, and the agent will be billed a fixed rate for the conversation. Billed per message: If the agent delivers a message that the user doesn't reply to within 24 hours, the agent will be billed for the individual message, similar to a non-conversational agent.

Conversational versus non-conversational agents

There are two main billing categories: conversational and non-conversational. The non-conversational category includes the Basic Message and Single Message categories, which are functionally identical. An agent in either of these categories is billed as a non-conversational agent.

The key difference in the billing categories is between conversational and non-conversational agents:

• Non-conversational agents are billed for each message they deliver to the user.

  • This category is best for agents that don't expect frequent replies.

• Conversational agents are billed a flat rate for conversations, which include all messages exchanged within a 24-hour period.

  • This category is best for agents that engage in multi-turn conversations with users.

Billing events

Five different types of billing events are recorded in the billing event reports. These events include A2P and P2A messages.

• A2P (Application-to-Person): Sent by the brand.
• P2A (Person-to-Application): Sent by the user.

The following table describes each billing event as it applies to non-conversational and conversational agents.

Event	Description	Non-conversational agents	Conversational agents
basic_message	A2P message that includes only text with 160 characters or less. If the text includes a URL for a website with openGraph tags, the message may show an image preview, at no added charge to the partner.	Always treated as an individual billing event, regardless of whether the user replies.	Treated as an individual billing event, unless the user replies within 24 hours. In that case, the message becomes part of an a2p_conversation.
single_message	A2P message that includes multimedia and/or text with more than 160 characters.	Always treated as an individual billing event, regardless of whether the user replies.	Treated as an individual billing event, unless the user replies within 24 hours. In that case, the message becomes part of an a2p_conversation.
a2p_conversation (brand initiated)	Initiated when a user responds to an A2P message within 24 hours of receiving it, outside of an existing conversation.	N/A. Non-conversational agents never generate this type of event.	If a P2A message is delivered within 24 hours of multiple A2P messages, only the A2P message that immediately preceded the P2A message is used to initiate the conversation. This A2P message, and any messages delivered within the next 24 hours, are part of the a2p_conversation.
p2a_conversation (user initiated)	Initiated when an agent responds to a P2A message within 24 hours of receiving it, outside of an existing conversation.	N/A. Non-conversational agents never generate this type of event.	If an A2P message is delivered within 24 hours of multiple P2A messages, only the P2A message that immediately preceded the A2P message is used to initiate the conversation. This P2A message, and any messages delivered within the next 24 hours, are part of the p2a_conversation.
p2a_message	P2A message of any type.	Always treated as an individual billing event, regardless of whether the agent replies.	Treated as an individual billing event, unless the agent replies within 24 hours.

Billing events versus billing categories

The basic_message and single_message billing events shouldn't be confused with the Basic Message and Single Message billing categories.

• Any agent (no matter its billing category) can generate basic_message and single_message billing events.

• The Basic Message and Single Message billing categories are used to classify non-conversational agents. Agents in these billing categories don't generate conversational billing events (a2p_conversations or p2a_conversations). Instead, they generate individual basic_message, single_message, and p2a_message billing events.

Billing report generation

Only agents with non-tester traffic generate billing events. Activity from test phone numbers doesn't appear in billing event reports.

These reports assume that events are billed when messages are delivered, not when messages are sent. An undelivered message or a message canceled before delivery doesn't trigger a billing event.

Billing report format

Billing event reports use the filename format rbm_billable_events_YYYY-MM-DD.csv. The date in the filename is the file generation date.

Each line in the report is a record representing a single billing event. Fields within a record are tab separated. For example, two A2P conversations with the same agent would generate two billing events and two records in the billing event report.

Each record in the report contains the following information for each billing event:

Field	Format	Description	Example
billing_event_id	string	UUID identifier. A random number generated for each new event at the time it is created.	242f1d9f-7c3f-4e5b-ab3f-818f188fa3ff
type	string	Type of event: basic_message single_message a2p_conversation p2a_conversation p2a_message	single_message
agent_id	string	Unique identifier for the agent that participated in the event.	[e-mail]
agent_owner	string	Email address of the current owner of the partner account where the agent was created.	[e-mail]
billing_party	string	Party who bills for events. google carrier	carrier
max_duration_single_message	number	Maximum time (in hours) allowed for a user to respond to an agent message before the conversation initiation window closes and the message is classified as a single_message event.	24
max_duration_a2p_conversation	number	Maximum duration of an A2P conversation, in hours. Measured from the first user response to the agent's initial message.	24
max_duration_p2a_conversation	number	Maximum duration of a P2A conversation, in hours. Measured from the first user message in the conversation.	24
start_time	YYYY-mm-ddTHH:00:00Z	The UTC date/time the event started in ISO 8601 format rounded to the nearest hour. For a2p_conversation and p2a_conversation events, this is the time that the conversation started. For single_message and basic_message events, this is the time that the event took place.	2019-07-25T08:00:00Z
duration	number	Event duration, rounded to the nearest minute. When the event type is single_message or basic_message, the value is 0.	45
mt_messages	number	Number of mobile-terminated (A2P) messages in the event.	11
mo_messages	number	Number of mobile-originated (P2A) messages in the event.	9
size_kilobytes	number	Size of all files attached to messages in the event, rounded to the nearest kilobyte (1kB = 1024 bytes).	912
agent_name	string	Name of the agent that participated in the event.	XYZ Mobile USA
owner_name	string	Name of the current owner of the partner account where the agent was created.	XYZ Mobile

Sample billing event report

A sample billing report file is available for download.

Typical file size

A daily report from an active RBM partner may contain around 53,000 records and be approximately 8Mb in size.

Activity logs

Activity logs provide raw data about activity on the RBM platform. You can use these logs to audit billing events and create custom events.

Activity logs are only available to carriers who have RBM traffic on their networks and enable RCS activity with Google RCS Cloud under their own Terms of Service (ToS). If you use Google RCS Cloud under Google's ToS, you won't have access to activity logs.

Note: Activity logs contain detailed transaction information and subscriber MSISDNs. Because activity logs contain Personal Identifiable Information (PII), they are only available when a carrier is operating RCS under their own Terms of Service.

Activity log format

Activity logs use the filename format rbm_activity_YYYY-MM-DD.csv. The date in the filename is the file generation date.

Fields in a record are tab separated, and there is one record per line.

Each record in the activity log contains the following fields for each activity:

Field	Format	Description	Example
activity_id	string	Unique identifier for the activity.	b422e1d3-ac99-442a-853d-a875d5e61762
billing_event_id	string	Unique identifier for the associated billing event. Can be empty if the activity is not associated with a billing event, such as a text_message without corresponding delivery_receipt_event.	91yeb201-7c3b-412b-98d2-b0a0f7abe536
agent_id	string	Unique identifier for the agent.	[e-mail]
user_id	string	MSISDN of the user.	918369110173
direction	string	The direction where the message is sent: MT (mobile terminating) for agent-to-user activities MO (mobile originating) for user-to-agent activities	MT
time	YYYY-mm-ddTHH:MM:SS.SSSZ	Date and time when the event was submitted to the RBM platform in UTC format. See Timestamps.	2019-07-25T00:29:07.033Z
type	string	Type of activity: text_message file_transfer rich_card/carousel suggestion_tap delivery_receipt_event read_receipt_event spam_report	text_message
size_bytes	string	Size of files attached to the activity, in bytes.	912

Timestamps

The timestamps in activity logs record when an event was submitted to the RBM platform. For events that deliver content to a user, the event won't be recorded in the activity log until the message is delivered.

For example, if an RBM message is sent to a user on Wednesday at 13:00, and the recipient is offline until Sunday 9:00, the event will appear in the activity log generated for Sunday, but the timestamp will be Wednesday, 13:00.

FAQ

What is a conversation?

In RBM, a conversation is a series of messages exchanged between a user and a conversational agent during a 24-hour period. Only agents with a Conversational billing category can generate conversations and be charged for these billing events:

• A2P conversation: Conversation initiated by the brand.
• P2A conversation: Conversation initiated by the user.

How conversations work

• Start: A conversation begins when one party (the agent or user) responds to a message from the other party within 24 hours of receiving it, outside of any existing conversation.

  • A2P conversation: Starts when the user responds to the agent's message.
  • P2A conversation: Starts when the agent responds to the user's message.

• Conversation window: The conversation remains active for 24 hours after it started. The conversation includes all messages within this 24-hour window, as well as the very first message that was initially responded to.

• Billing: Instead of billing for each individual message, conversational agents are billed based on the entire conversation. This means the cost is associated with the conversation thread, not the number of messages within it.

Important:

• Conversations don't apply to non-conversational agents. Agents with a Basic Message or Single Message billing category are billed per message, regardless of whether the user replies.

• For conversational agents, the generation of billing event reports and activity logs can be delayed by up to two days. This delay allows RBM to capture all messages within a conversation before calculating the billing event.