Oracle Responsys SMS Public Aggregator Network Guide

Overview

This guide is for SMS aggregators who want to become Oracle Partners in providing SMS service to Oracle Responsys customers. From their Oracle Responsys sessions, Oracle Responsys customers who have been enabled to do so can order mobile codes provided by SMS aggregators. SMS aggregators provision the requested mobile codes for customers. SMS aggregators that are activated for the SMS Public Aggregator Network (SPAN) provide the SMS service plans that are available to Responsys customers.

Tip: This guide is for SMS aggregators who participate in SPAN. If you are an Oracle Responsys customer who wants to manage SMS aggregators for your account, please refer instead to the Oracle Responsys online help topic Managing SMS aggregators for your account.

To become part of SPAN, you must register your services in the Oracle Responsys system and enter configuration details. You must also complete configuration tasks on your SMS aggregator systems. Those tasks are described in this guide. Once completed, customers will then be able to order mobile codes from you from within Oracle Responsys. Once you have provisioned them, customers can use the mobile codes to send their SMS campaigns.

As an SMS aggregator participating in SPAN, there are four main tasks for you to perform:

  • Onboarding: Onboarding is a one-time task that involves two steps. In step one, you log into Oracle Responsys and register your company as an SMS aggregator. In step two, you set up your SMS aggregator system to communicate with Oracle Responsys, using information provided in Step 1, so that SMS campaign launches are processed smoothly.
  • Configuring: In this task, you will enter the information required by Responsys, so that you can activate your company in the SMS Public Aggregator Network. After activation, Responsys users will see your plan information in the system and will be able to purchase mobile codes from you.
  • Servicing orders from Oracle Responsys customers: Servicing orders from Oracle Responsys customers is an ongoing task. After your services are activated in Oracle Responsys, customers will be able to order codes from you for use in sending SMS campaigns. Before they can use what they have ordered, you must provision the codes for customers to use and complete the order in Responsys.
  • Managing customer accounts in Responsys: Other ongoing tasks for SMS aggregators are servicing sender name change requests from Oracle Responsys customers and uploading support ticket details.

Commonly used terms

SPAN: SMS Public Aggregator Network. An Oracle framework which allows third-party aggregators to be set up on the system, available to all Oracle Responsys SMS customers.

Partner: An SMS aggregator or telecommunications company willing to be an Oracle partner.

Short code: Special telephone number, usually 5 or 6 digits long, used to send messages to and receive messages from mobile phones in one country.

Long code: Special telephone number similar in functionality to a short code. Long codes are longer than short codes (15 digits maximum) and can be made accessible internationally.

Mobile-originated (MO) Message: Message sent from a user’s mobile phone to a short or long code.

Mobile-terminated (MT) Message: Message sent by a short code to a user’s mobile phone.

Delivery receipts (DR): Message sent from the SMS aggregator to Responsys after the SMS aggregator sends the message. The DR message contains delivery information about each message, such as the carrier and the status codes.

Customers: In this document, “customers” refer to Oracle Responsys users who order short codes and long codes through plans provided by SMS aggregators through SPAN.

Notes

  • This guide assumes that the SMS aggregator partner has already completed the business evaluation criteria presented to them and agree to comply with it.
  • SMS aggregator partner setup can be configured for a maximum throughput of 5 million message per hour.
  • Only dedicated short codes can be set up for SMS aggregator partners. Oracle Responsys does not support shared short codes.
  • Route types are simply labels in our system. There is no meaning associated to them. If you have a request for a new route type entry, please contact Oracle during the onboarding process.
  • It is responsibility of the SMS aggregator partner to not forward MO for MT-Transactional and MT-Priority codes. If Oracle Responsys gets an MO for them, then we simply process them.

Onboarding

Your first task in setting your company up as an SMS aggregator partner in Responsys involves the following steps:

  1. Register your service in Oracle Responsys
  2. Set up your infrastructure to support SPAN

Step 1: Register your service in Oracle Responsys

After Oracle sets you up as an SMS aggregator in Responsys, you will receive a welcome email. Log in to Responsys to register your company as an SMS aggregator partner.

To register your company as an SMS aggregator partner:

  1. Using the Responsys SMS Aggregator Partner credentials sent to you, log in to Responsys. If this is your first time logging in to Responsys, follow the instructions on the page to reset the temporary password.

    Tip: Keep a record of your Responsys user name and password, because you will use it later for editing your Aggregator settings and for servicing orders for short and/or long code from Responsys users.

  2. From the Manage Aggregator page, click the Get started icon.
    SPAN Get Started icon
  3. From the Add Aggregator dialog, complete the following fields:

    Important: This screen is a one-time setting. Ensure that the values are correct. If you need to change them, please contact Oracle Support.

    • Aggregator name: This is the name used for the {aggregator} attribute in the Oracle SMS MO listener URL and the Delivery Receipt (DR) endpoint URL.
    • Display name: This is your aggregator name, as displayed in Responsys to yourself and to Responsys customers after activation.
    • Aggregator URL: MT endpoint URL, which Responsys uses to send to the aggregator's system. For example, when Responsys sends an SMS campaign using MT, the system will take this URL and append the credentials, message and mobile number, and then post it to the SMS aggregator system.
    • Limit send rate to ... messages per hour: Enter your system's throttling limit. By default, Responsys will send 1 million messages per hour. This is an approximate count, the real throughput may vary by 1-2%. The maximum value is 5 million. To increase the send rate, please contact Oracle Support.
  4. Optionally, click Advanced Settings to edit the following settings:
    • Connection Timeout: Amount of time that Responsys will wait for a response from the SMS aggregator. By default, this is 1000 msec.
    • Retry Count: Number of times that Responsys will retry sending the message if there is a connection timeout. By default, this is 1 retry.
  5. Click Add.
  6. From the Confirmation dialog, click Submit to send your aggregator settings to Responsys. Otherwise, click Back to modify your settings. After you click Submit, the Useful Information dialog confirms that your aggregator settings are configured in Responsys.

    Important: You will need the information displayed on the Useful information dialog in Step 2 of onboarding. It provides one or more Oracle IP address(es) to allowlist with your system and the endpoint URLs you must use to communicate with Responsys. You can always find it again by accessing the Configuration settings in your aggregator profile.

  7. Click OK to dismiss the dialog. Your aggregator information is displayed in the table on the Manage Aggregator page, but is it flagged with a red icon. This icon indicates that the aggregator's onboarding and configuration is not completed yet.
  8. Log out of Responsys and complete Step 2: Set up your infrastructure to support SPAN.

Step 2: Set up your infrastructure to support SPAN

 

Before you can accept traffic from Oracle systems, you must perform the tasks described in the Oracle Responsys Integration Guide for SMS Aggregators. This document describes how to implement the interfaces on your systems for MT traffic from Responsys and to make MO and Delivery Receipt (DR) status calls to Responsys. It also discusses allowlisting and security certificate requirements.

Configuring

Your next task in setting your company up as an SMS aggregator partner in Responsys involves the following steps:

Optionally, you can view the Configuration settings from your initial registration.

Step 1: Enter short codes and/or long codes for testing connectivity between your system and Responsys

Use the Manage codes tab to enter codes for testing connectivity between your system and Responsys. These codes cannot be used by Responsys customers.

To add short codes or long codes for testing:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Configure icon (Shows the SPAN Configure icon).
  3. Click Manage codes.
  4. From the button on the upper right side of the page, choose Add Short Code or Add Long Code.
  5. On the Add ... Code dialog, enter the following information:
    1. Enter the Short code if you are adding a short code, or enter the Long code if you are adding a long code.
    2. Select a Country. If you are adding a long code, you may select one or more countries.
    3. Select a Route type.
    4. Enter a Sender name.
    5. Where applicable, enter User name and Password. Use the authorization for the selected route type. This is same authorization Responsys uses to place the MT call to your system.
  6. Click Add.

Tip: Optionally, you can store credentials for each route type, so that when you use the Manage codes page to add a code, you will not have to enter the credentials. To store credentials, click the Manage credential for route types link. On the resulting page, locate the route type for which you want to store credentials. Click its An image of the Edit iconEdit icon. Enter the user name and password, and then click Save.

Step 2: Upload Delivery Receipt status codes

Use the Delivery receipt status code tab to configure your DR status codes and map them to Responsys categories and sub categories. To edit the DR status codes displayed on this page, edit and re-upload the mapping file.

To upload Delivery Receipt status codes:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  3. Click Delivery Receipt status code. When you first access this tab, you will see a message stating that you do not have any details defined.
  4. From the Delivery Receipt status code details page, click the View the sample .csv file link.
  5. Scroll to the bottom of the Sample file format dialog, to the Sample .csv file box.
  6. Click the Copy to Clipboard icon Copy to Clipboard icon.
  7. Paste the sample .csv file into the editor you will use to create your DR status codes file.
  8. Enter your Delivery Receipt status code information into the CSV file. If you already have a DR status codes file, edit the file to include the required columns, which are described on the Sample file format dialog.
    1. Create a new row for each unique DR Status Code that your system will send.
    2. For each code, add a DR Status Code name and a DR Status Code Description.
    3. For each code, assign a Responsys Category + Sub Category combination from those shown in the template.
  9. Return to the page and click Upload file. Once the upload completes, the table displays the Delivery Receipt status codes and their mappings to the Responsys Categories+Sub Categories. The Last updated field is updated to show the time and date of your latest upload.

Step 3: Upload Pricing and Performance details

Use the Pricing and Performance tab to add the pricing and performance details for each plan:

  • Pricing details include the setup fee, monthly fee, and price (cost per thousand messages) for the short codes and long codes you provide.
  • Performance details are your deliverability scores for each plan. Responsys users will see these values when an Oracle-derived score is not available.

To change the details displayed on this page, edit and re-upload the pricing and performance details file. Pricing changes will apply to only new orders, not to existing orders.

Important: SMS aggregators work directly with customers for setting up new service contracts and for billing. These activities do not happen in Oracle Responsys.

To upload pricing and performance details:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  3. Click Pricing and Performance. When you first access this tab, you will see a message stating that you do not have any details defined.
  4. Click View sample .csv file to view instructions for creating the CSV file and to copy a sample.
  5. Scroll to the bottom of the Sample file format dialog, to the Sample .csv file box.
  6. Click the Copy to Clipboard icon Copy to Clipboard icon.
  7. Paste the sample .csv file into the editor you will use to create your pricing and performance details file.
  8. Following the instructions on the Sample file format dialog, create the CSV file.

    Important: Please carefully read the instructions on the Sample file format dialog, particularly for the Setup fee, Monthly fee, and Price columns for each plan that you enter.

    Regarding Declared Deliverability, you can optionally provide a deliverability score that will be displayed for the plan when an Oracle-derived score is not available. The deliverability score is a percent calculated by dividing the total messages delivered divided by the number of messages intended. The Oracle-derived score is computed with data from the past 90 days.

  9. Click Upload file from the Pricing and Performance tab or Upload now from the Sample file format dialog. Browse and upload the Pricing and Performance CSV file that you created. The pricing and performance details are displayed on the page.

Step 4: Enter your Contact information

Use the Contact information tab to enter the SMS aggregator help desk information, which Responsys users that are your customers will use to contact you.

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  3. Click Contact information.
  4. On the Contact information tab, enter the following fields:
    1. Enter your help desk's Email address and Description. If you have more than one email address to enter, use the Add more button to add additional fields. For example, you may have different help desk email addresses for each country in which you do business.
    2. For the Phone number section, enter the help desk Phone number and Description. If you have more than one phone number to enter, use the Add more button to add additional fields.
    3. Optionally, enter your Support portal URL.
  5. Click Save. Or, if you want to restore the previous values, click Discard changes.

Step 5: Send a test message to test your connection with Responsys

After you have entered all of the details for activation, but before you activate your company to be part of SPAN, you can send a test MT from the Manage Aggregator page.

Before you begin: Ensure that you have used the Manage Codes tab in the aggregator settings to add your test code(s).

To send a test MT message:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Test icon (Shows the Test icon for SPAN).
  3. From the Test dialog:
    1. Select the Code you want to test. The codes in this list are the codes you entered on the Manage Codes tab in the aggregator settings.
    2. Enter the Mobile number that will receive the test message. The country code is automatically added for the country associated with the code you selected, so you only need to enter the mobile number itself.
    3. Type a Test message in the field provided.
    4. Click Send test message. The Test Result dialog returns the message status (for example, "Message successfully sent").
    5. From the Test Result dialog, click Done to close the dialog or click Send another test message to return to the Test dialog.
  4. Repeat for other codes you want to test.

Step 6: Activate your aggregator profile in Responsys

After you have completed steps 1-4 above, the icon displayed next to your aggregator name on the Manage Aggregator page changes from red (indicating that additional details were needed) to yellow. The yellow icon indicates that your company is ready to be activated as an SMS aggregator in Responsys.

Important: Before you activate your aggregator profile in Responsys, ensure that you have added a test code and have tested your connection.

To activate aggregator:

  1. Navigate to the Manage Aggregator page.
    • If you are on the aggregator configuration page, click the Back to manage aggregator link.
    • If you are logged out of Responsys, log in again using your Responsys SMS aggregator credentials.
  2. Locate and click the Activate aggregator button.
  3. From the Activate aggregator profile dialog, read the instructions on the dialog.
    • If you have not tested your connection by sending a test message, click Cancel and perform the required testing.
    • If you have successfully sent a test message, click Activate.

The Manage Aggregator page displays an "Activated" status for your aggregator profile. Your company is now added to the SMS Public Aggregator Network in Responsys. Your plans will be available for Responsys users to find and to order.

Tip: When needed, you can return to the Manage Aggregator page and modify some settings in your aggregator profile, such as your DR codes, your price list, and your contact information.

View Configuration settings

You can view your configuration settings. This is the information you added in the registration step and the information displayed on the Useful information dialog that was displayed after you completed registration.

Note: You cannot change these values from the aggregator profile settings. If you must change any of these values, contact Oracle Support.

To view Configuration settings:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the View useful information icon (Shows the View useful information icon). Alternatively, if you are already viewing your aggregator profile pages, you can select the Configuration settings tab.
    The configuration settings and useful information from registration step are displayed.

Servicing orders from Oracle Responsys customers

Responsys users can order long or short codes from SMS aggregators that support the countries where they want to send SMS campaigns and the types of messages they want to send. Responsys users are able to compare the setup fees and cost per message of each potential SMS aggregator's plan before they place their orders.

After a Responsys user customer places an order for one of the plans in your price list, the order is sent to you for processing. Oracle Responsys will send you an email notification and the order will appear in your Manage orders page.

If you accept the Responsys user customer's order and complete provisioning for the customer, then the customer can then use the code(s) that they purchased from you for sending their SMS campaigns.

To service orders from Oracle Responsys customers:

  1. When you receive an email from Oracle Responsys with the subject "Responsys customer has placed order for codes", open the email to review the order details.
  2. Click the link in the email to go to the Responsys login page, and use your SMS Aggregator Partner credentials to log in.
  3. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  4. Click Manage orders.
  5. On the Open orders tab, click the arrows to review the orders from each Responsys account.
    • To accept the order, click the green check box icon in the Order Status column.
    • To reject the order, click the red "X" box icon.

    Tip: Optionally, you can store credentials for each route type for each Responsys account, so that when you use the Complete order page, you will not have to enter the credentials. To store credentials, click the Manage credential for route types link for the account. On the resulting page, locate the route type for which you want to store credentials. Click its An image of the Edit iconEdit icon. Enter the user name and password, and then click Save.

  6. If you accept the order, the Complete order dialog is displayed. Complete the fields as follows:
    1. Enter the Account ID. This is the Responsys customer's account ID in your internal system, not their Responsys account ID.
    2. Enter the Code.
    3. Sender name (where applicable) shows the name that the customer requested.
      • You can change the name, if needed. For example, if the sender name is not available, you can change it to an available name. Each sender name is limited to 11 characters and may include letters (a-z or A-Z) and numbers (0-9).
      • Sender names are required when the route type is Mobile Terminated (MT) - One way bulk, but they are optional for other route types.
      • If the customer did not request a sender name, this field shows "Not Requested".
    4. Optionally, enter a Comment of 150 characters or less. This message will be displayed to the Responsys customer.
    5. In the Account settings section, enter the User name and Password. These are the credentials that Responsys uses when posting MT messages through this code to the SMS aggregator system. If you have saved the credential for the route type for this account, these fields are not displayed.
  7. Click Complete order to view the confirmation dialog, or click Cancel to close the dialog without saving.
  8. Review the confirmation dialog, and either click Complete order to change the order status to "Completed" or click Cancel to close the dialog without saving.
    • A message is displayed, stating that the order was completed successfully.
    • The system generates the code (which you can see on the Past orders tab).
    • The completed order is moved from the Open orders tab to the Past orders tab. Optionally, click Past orders to view it.
    • The Responsys user customer will see the code in their view of the SPAN settings.
  9. Repeat steps 5-8 for each order that you need to process.
  10. When you are finished, sign out of Responsys: Click the user icon in the upper left corner of the page, and select Sign Out.

To view past orders from Oracle Responsys customers:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  3. Click Manage orders.
  4. Click Past orders, and then click the arrow next to the Responsys customer account for which you would like to view past orders.

    The resulting table shows the order details, such as order completion date, what the customer ordered, and the status.

  5. Optionally, move your mouse cursor over the Details icon of a row to view more information: the message sent to the customer, the date that the customer placed the order, and the pricing details of the order.

Managing customer accounts in Responsys

This section provides instructions for other ongoing account management tasks for SPAN aggregators:

Servicing sender name change requests

Your Responsys SPAN customers can submit sender name change requests. You will receive an email message when a customer requests a sender name change for their account.

Important: SMS aggregators are responsible for verifying outside of the Responsys system that the customer's sender name is unique and that it meets the regulations for the country in which the customer will use it.

To service a sender name change request:

  1. When you receive an email from Oracle Responsys with the subject "Responsys customer has placed sender name request", open the email to review the request details.
  2. Click the link in the email to go to the Responsys login page, and use your SMS Aggregator Partner credentials to log in.
  3. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  4. Click Manage Sender Name request.
  5. On the Open request tab, click the arrows to review the requests from each Responsys account.
    • To accept the request, click the green check box icon in the Request Status column. This displays the Complete request dialog, where you can enter a comment. Click Complete request to continue.
    • To reject the request, click the red "X" box icon. This displays the Complete request dialog, where you must enter a reason for rejecting the request. Click Reject request to continue.
  6. Review the confirmation dialog and follow its instructions for continuing, or click Cancel to close the dialog without saving.
    • If you accepted the request, a message is displayed, stating that the request was completed successfully. The request's status is changed to Completed.
    • If you rejected the request, a message is displayed, stating that the request was rejected. The request's status is changed to Rejected.
    • The processed request is moved from the Open requests tab to the Past requests tab. Optionally, click Past requests to view it.
    • If accepted, the Responsys user customer will see the sender name in their view of the SPAN settings.
  7. Repeat steps 5-8 for each request that you need to process.
  8. When you are finished, sign out of Responsys: Click the user icon in the upper left corner of the page, and select Sign Out.

Uploading support ticket data

You can upload a data file containing support tickets that were created or resolved for Oracle Responsys customers during the past 90 days. (These support tickets are handled in your own support ticket system.) The file can contain tickets for all of your customers, but because each record has the customer's account ID, each Responsys SPAN customer will see only the support tickets for their account.

Note: Each file upload completely refreshes your support ticket data in Responsys; it does not add to the data that you have already uploaded.

To upload support ticket data:

  1. Log in to Responsys using your SMS Aggregator Partner credentials.
  2. On the Manage Aggregators page, click the Configure icon (Shows the Configure icon for SPAN).
  3. Click Support ticket details. (When you first view this tab, you will see information about the support ticket data file.)
  4. Click View sample SupportTicket.csv file to view instructions for creating the CSV file and to copy a sample.
  5. Scroll to the bottom of the Sample Support Ticket dialog, to the Sample supportTicket.csv file box.
  6. Click the Copy to Clipboard iconCopy to Clipboard icon.
  7. Paste the sample .csv file into the editor you will use to create your support ticket details file.
  8. Following the instructions on the Sample Support Ticket dialog, create the CSV file.

    Important: Please carefully read the instructions on the Sample Support Ticket dialog, particularly for the Account ID column, file size limit (5 MB), and restrictions for dates opened and closed (within past 90 days). Having the correct information ensures that each Responsys customer will see their support tickets.

  9. Click Upload file from the Support ticket details tab or Upload now from the Sample Support Ticket dialog. Browse and upload the CSV file that you created. The support ticket details are displayed on the page.

Frequently Asked Questions

How do I contact Oracle Support?

For assistance with SPAN configuration issues, please contact Oracle Partner Network Support.

If your company is an active member of the Oracle Partner Network Program, your company's Partner Administrator (manages your company's relationship with Oracle) has been provided a unique Company ID for your organization. Use this Company ID when creating a Service Request (SR). For your SR to be routed promptly, ensure that the SR mentions that you are a Responsys SMS aggregator partner participating in SPAN.

How do I log out of Responsys when I'm done with my session?

To log out of Responsys: Click the icon in the upper left corner of the page (a circle with the first initial of the user name) to display the user actions menu, and then select Sign Out.

Oracle Responsys, SMS aggregators, SMS partner aggregator, SMS aggregator, SMS aggregator partner, SMS Public Aggregator Network, SPAN