Billing event reports and activity logs

RBM creates data files that report user and agent activity on summary and transactional levels. Data is separated into multiple files:

File Description Who has access
Billing event report A record of billable events between launched agents and users All carriers that have RBM traffic on their networks
Activity log Raw RBM platform activity data Carriers that have RBM traffic on their networks and enable RCS activity with Jibe Cloud under their own Terms of Service (ToS)

Generation

Billing event reports and Activity logs have a two day delay in generation.

Google reports an activity event only when the billing session it belongs to is complete. A session can take up to 24 hours to complete and, our billing pipeline executes once a day and only reports billing sessions that are sure to have completed (so are at least at least 24 hours old).

For example:

  • A message is sent on day d and initiates a billing session, but it has missed the pipeline execution 1 hour earlier. Therefore, no activity event is reported.

  • When the pipeline runs again on d+1, the session the message initiated is only 23 hours old. Therefore, no activity event for this message is reported on d+1.

  • When the pipeline runs again on d+2, the session has completed so the activity event is reported along with the billing session.

Storage and access

Data files are encrypted at rest and in transfer.

To retrieve data files by SFTP, you need to 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 report files have been generated yet, you will see an SFTP error similar to remote readdir("/"): No such file or directory. This is expected.

A file won't be generated if there is no RBM traffic to report. This means there may be some days when files are not generated. Contact rbm-support@google.com if you require empty files to be generated in this situation to simplify your processing.

Refresh and retention

Each data file represents one day of platform usage in UTC time. Records for a given day are generated once and finalized within 2 days (48 hours) after the day ends. If you load these files into a data warehouse, you can update the current month's metrics.

A file is not generated if there is no activity to account for.

The date in the name of each file is the date that the file was generated. The records in the file will cover the UTC day that comes 2 days before the file date.

The export process generating the files executes between 2 and 4am PST.

Data files are retained for a maximum of 30 days before being deleted.

Billing event reports

Billing event reports are records of billable events calculated from underlying messages using the suggested units of billing. Billable events contain confidential information, but no user PII (e.g., no MSISDN, hashed MSISDN or any user unique identifier).

Only launched agents generate billing events. Activity from yet to be launched or unlaunched agents doesn't appear in billing reports.

The billing reports assume that events are billed on delivery of messages, not when messages are sent. An undelivered or a message revoked before delivery doesn't trigger a billing event.

Each RBM agent has a Billing Category, set by the agent developer before submitting the agent for launch. The Billing Category determines whether messages that the agent sends are discrete or whether they may be combined into conversational billing events.

There are five types of billable events:

Event Definition
Basic Message

An application-to-person (A2P) message that

  • is up to 160 characters
  • contains only text

Conversational agents only: if a P2A message is delivered as a response to an A2P message within the next 24 hours, the Basic Message becomes part of an A2P conversation; otherwise, the session terminates. A Basic Message is always delivered from an agent to a user.

Single Message

An application-to-person (A2P) message that

  • contains multimedia or text with more than 160 characters

Conversational agents only: if a P2A message is delivered in the next 24 hours, the Single Message becomes part of an A2P conversation; otherwise, the session terminates. A Single Message is always delivered from an agent to a user.

A2P Conversation Applies to conversational agents only: An A2P Conversation is initiated when a P2A message is delivered within 24 hours of an A2P Single Message or A2P Basic Message. Note that 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 create the conversation session. This A2P Message, along with any messages delivered within the next 24 hours, are part of the new A2P conversation.
P2A Conversation Applies to conversational agents only: A P2A Conversation is initiated when there is no active session (A2P Single Message, A2P Conversation, or P2A Conversation) and a P2A message is delivered, and the business responds within 24 hours.
P2A Message Non-conversational agents: A P2A message sent from a user towards an agent with a Billing Category of Single Message or Basic Message.

Conversational agents: A P2A message sent from a user towards an agent where there is no existing conversation and the agent does not return a reply.

Availability

Billing event reports are available to all carriers that have RBM traffic on their networks.

Format

Billing event reports use the filename format YYYY/MM/DD/rbm_billable_events_YYYY-MM-DD.csv.

The date in the filename is the date that the file was generated. The records in the file generally cover activity for the date two days before the file generation date.

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

There will be one record for each billing event. For example, two A2P conversations with the same agent will generate two billing events and two records in the billing report.

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

Field Format Description Example
billing_event_id string The UUID identifier, a random number, generated for each new event at the time it is created.
type string The type of event:
  • basic_message
  • single_message
  • a2p_conversation
  • p2a_conversation
  • p2a_message
single_message
agent_id string The identifier of the agent that participated in the event. rbm-welcome-bot@rbm.goog
agent_owner string The email address of the current owner of the partner account where the agent was created. This value is taken from the 'RBM Google Account' field provided when the partner registered to use RBM. name@aggregator.com
billing_party string The party who bills for events.
  • google
  • carrier
carrier
max_duration_single_message number The duration, in hours, for an agent's message to go without receiving a response to identify a single message session. 24
max_duration_a2p_conversation number The maximum duration of an A2P session, in hours. Measured from the first user response to the agent's initial message. 24
max_duration_p2a_conversation number The maximum duration of a P2A session, 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 session started.
  • For single_message and basic_message events, this is the time that the event took place.
2019-07-25T08:00:00Z
duration number The duration of the event, rounded to the nearest minute.

When the event type is single_message or basic_message, this will be 0.

45
mt_messages number The number of mobile-terminated messages in the event. 11
mo_messages number The number of mobile-originated messages in the event. 9
size_kilobytes number The size of all files attached to messages in the event, rounded to the nearest kilobyte (1kB = 1024 bytes). 912
agent_name string

The agent that participated in the event.

XYZ Mobile USA
owner_name string The email address of the current owner of the partner account where the agent was created. This value is taken from the 'RBM Google Account' field provided when the partner registered to use RBM. XYZ Mobile

Sample file

A sample billing report file is available for download.

Typical file size

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

Activity logs

Activity logs are the raw data log of activity on the RBM platform for the purposes of auditing billable events and constructing custom events.

Availability

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

Format

Activity logs use the filename format YYYY/MM/DD/rbm_activity_YYYY-MM-DD.csv.

The date in the filename is the date that the file is generated. The records in the file will generally cover activity for the day that was 2 days before this 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 event.

Field Format Description Example
activity_id string The identifier for the activity.
billing_event_id string The identifier for the billing event the activity took place in. Can be empty if the activity is not associated with any session, such as a text_message without corresponding delivery_receipt_event.
agent_id string The identifier of the agent. welcome-bot@rbm.goog
user_id string The MSISDN of the user. 918369110173
direction string The direction that the message was 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 The UTC date/time that the event was submitted to the RBM platform. See note. 2019-07-25T00:29:07.033Z
type string The 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 The size of files attached to the activity, in bytes. 912

A note on timestamps

The timestamps in Activity logs record the time that an event was submitted to the RBM platform. For events that deliver content to a user, the event won't be written to the Activity log until the message has been delivered.

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