Subscribe to the API

API Authentication

This API requires a 2-legged authentication managed by our OAuth 2.0 proxy V3 authorization server. Please follow the method described here.

In short, you use your Orange Developer Authorization header as authorization_header for the Basic authentication with Orange Developer. It allows you to to authenticate to Orange Developer API.

You get the Authorization header credentials when you register your application on the Orange Developer Console.

curl -X POST \
-H "Authorization: {authorization_header}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

In response, you will get an API access_token

{
       "token_type": "Bearer",
       "access_token": "_Bearer_Access_Token_Provided_ByOrangeDeveloper_",
       "expires_in": "3600"
}

The token validity period is 1 hour (3600 seconds).

Endpoint

https://api.orange.com/bothub/v1

GSMA Authentication

You now need to connect from OrangeDeveloper to our BotHub API exposition for GSMA interface. The GSMA interface requires a separate authorization with a JWT Token according to GSMA standard for RCS bot platform. An orange admin will provide you Bot ID & Bot private key. You will use them in next steps.

Explanation of the JWT Token:

It is composed of the below JWT token header & body and signed with the GSMA private key received from Orange administrator

JWT Token generation: It comes under your responsibility to generate the JWT token.

header: {
        alg: "RS256",
        typ: "JWT"
    }
payload :{
        iss: [ <GSMA_BotID> ],
        scope : "Chatbot message",
        aud: "https://api.orange.com/bothub/v1/gsma",
        exp: [ timestamp, currentTime+3600s ]
        iat: [ timestamp, currentTime ]
    }

Fields to append on your side:

• Iss is the bot Id you get during your bot OnBoarding process
• secret is the GSMA bot private Key you get during your bot OnBoarding process

Bot Onboarding Portal is here

You'll find in FAQs https://developer.orange.com/apis/bothub/FAQs TAB explanation on How to use the Bot Onboarding portal and get your Bot-id & Bot Private Key that will be used to generate the JWT Token. Note that this JWT Token is then used to generate the GSMA Token that is mandatory to send GSMA messages as you can see below

https://onboarding.bothub-messaging.orange.com/public/home

These 2 elements

• BotID : GSMA_BotID
• SecretKey : GSMA_SecretKey

are used to generate a JWT element (RFC 7519), with above content + the associated signature using GSMA_SecretKey

You get the GSMA_SecretKey inside the Onboarding portal once you onboarded the bot

&

&

& also in a email you receive from admin.onboarding@orange.com email account

In order to generate the JWT Token, you can use any way that suits you with a local implementation on your side (you can use one of the librairies provided on “Libraries for Token Signing/Verification” at the bottom of the https://JWT.IO page).

Please note that you don’t need to provide any public key to sign the token. You only need to use the GSMA bot private key that was shared by Orange admin to sign the key. Bothub itself uses the public key to validate your generated JWT token.

Below we provide an example for generating JWT token with https://jwt.io In https://JWT.IO provide following fields:

and in the secret base64 encoded field paste your GMSA bot private key: To derive Public key from bot private key you can use openssl or ssh-keygen with:

openssl rsa -in mykey.pem -pubout > mykey.pub

for example

For more inquiries, please contact (bothub_access_team@easymail.orange.com)

Creation Of GSMA access Token

With this API, you are able to create the GSMA access token that is used for your messages and events submission with request https://api.orange.com/bothub/v1/auth?JWT%20token={{_JWTToken_}} Or in CURL :

curl --location --request POST 'https://api.orange.com/bothub/v1/auth?JWT%20token=_JWTToken _-mB2Dw' \
--header 'accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer _Bearer_Access_Token_Provided_By_OrangeDeveloper_' \
--data-raw ''

With:

• JWTToken is the JWT token retrieved just in the step before
• Authorization Bearer is the Orange Developer authorization token.

This request returns the GSMA access token that will be used in sending messages or events.

Response for GSMA token something like:

{ "accessToken": "string", "expiresIn": "string", "scope": "string", "timeStamp": "string", "tokenType": "string" }

Sending Messages

With this API your bot can send RCS messages to any MSISDN.

curl --location --request POST 'https://api.orange.com/bothub/v1/bot/v1/[BotID]/messages' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AccessToken: _GSMAaccesstoken_' \
--header 'Authorization: Bearer _Bearer_Access_Token_Provided_By_OrangeDeveloper_' \
--data-raw '{
    "RCSMessage": {
        "trafficType": "advertisement",
        "textMessage": "Hello, world"
    }, 
    "messageContact": {
        "userContact": "+33612345678"
    }
}'

With:

• AccessToken is the GSMA token generated in the above step.
• Authorization is the Orange Developer token
• The bot ID is a URL parameter. This BotID will be provided to you by the Orange admin team once it is created on BotHub by us.
• The message body will be the message or event that needs to be sent to the end user in the GSMA format, for more details about the messages formats, you can visit GSMA FNW.11 specification

Other request example for message sending to bot:

POST /bothub/v1/bot/v1/{{botId}}/messages HTTP/1.1
Host: api.orange.com
accept: application/json
Content-Type: application/json
AccessToken: {{_GSMA access token_}}
Authorization: Bearer {{_Bearer_Access_Token_Provided_By_OrangeDeveloper_}}
{
    "msgId" : "{{msgId received on the GSMA Webhook during Triggering}}",
    "RCSMessage": {
        "trafficType": "advertisement",
        "textMessage": "This is test message for bot GSMA"
    }, 
    "messageContact": {
        "userContact": "{{msisdn}}"
    }
}

Expected response is the message "Hello, world" on the mobile phone of the tester.

As a developer, please be aware of some constraints existing on RBM - Google Backend, such as the Rich Card file size limitations of 40KB: https://developers.google.com/business-communications/rcs-business-messaging/guides/learn/best-practices?hl=en#rich_cards

The below sequence diagram shows BotHub interactions with GSMA Bot and Google RBM

Endpoint

https://api.orange.com/bothub/v1