API Usage – 5G Video Notifications

Prerequisites

Prior to interacting with any of the Alef APIs for the Video Notification Product, the developer must have completed the following:

  • Creation of an Alef Developer Portal Account
  • Subscription to the Alef Video Notification Product
  • Configuration of the Alef Video Notification Product

If there is any confusion as to how to complete these tasks. Please refer to the following document for instruction, https://developer.alefedge.com/get-started/create-edge-native-services/user-guide/ . If these three things have been completed, interaction with Alef Video Notification APIs can begin.

Swagger Documentation UI Execution

For greater understanding and simple interaction with the Alef Video Notification APIs, there is Swagger Documentation available. In addition to the simple execution of Alef Video Notification APIs, the Swagger documentation provides greater insight into the parameters, request bodies, and expected responses. This section will give greater insight into the parameters of these APIs.

When executing the Video Notification APIs from the Swagger UI, the first step in executing any API is clicking the “Try it out” button in the top right of the specific API drop-down you are testing, there is an image below for reference. The second step in the process would be filling in the parameters provided. The final step is clicking the blue “Execute” button just above the “Responses” section. After that, you have successfully used your first Alef Video Notification API from the Swagger UI.

If there are any issues with this or other workflows discussed in this document, please reach out to support@alefedge.com.

Add Campaign API

The Add Campaign API enables the developer to create a Video Notification Campaign where their content will be pushed in accordance with details entered by the Developer. Please note, not all of the parameters below are required fields. Required fields will be denoted on the Swagger UI and in the list below with a red asterisk.

The Parameters of the Add Campaign API:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.
  • Content – This piece of information is the video to be played. The Swagger UI provides a choose file interface in which you can select the video to be onboarded, from your machine.
  • Campaign Name – This piece of information is provided by the Developer and will be the name of the Campaign. This name can be leveraged in future APIs. Please note the name has to be all lowercase characters with a length less than 20.
  • Thumbnail – This piece of information is the photo the Developer wants to represent their video. If the Content is something like a movie trailer, it is likely the thumbnail would be the movie poster.
  • Time ZoneThis piece of information is the time zone in which the campaign is to be executed. It is a decimal value entered by the developer to represent the exact time at the location a campaign is to be started. For example, a campaign that will be executed in New York and to begin based on a New York time will require the value of this field to be -5. Please find the values for some time zones below:
    • -7 – Las Vegas GMT-7:00
    • 5.5 – Mumbai GMT+5:30
    • 3 – Moscow GMT+3:00
    • -5 – New York GMT-5:00
    • -5 – Miami GMT-5:00
    • 5.5 – Pune GMT+5:30 
    • 5.5 – Bangalore GMT+5:30
    • -7 – Santa Clara GMT-7:00
  • Channel Type – This piece of information is the channel in which the notification is to be sent. The options are:
    • SMS – Short Message Service
    • MMS – Multimedia Messaging Service
  • Call to Action URL – This piece of information is not required. If the developer wishes to include it, a Call-to-action URL is the URL which the enterprise can use to target their users.
  • Campaign Start Date – This piece of information is when the developer wants the Notifications Campaign to begin. Please note the format of this information is YYYY-MM-DDTHH:MM:SS
  • Campaign End Date – This piece of information is when the developer wants the Notifications Campaign to end. Please note the format of this information is YYYY-MM-DDTHH:MM:SS
  • SMS Text – This piece of information is the text to be associated with the Notification. It can be a call to action, a message supporting the video or anything else the Developer wants to share.
  • Call to Action Frequency – This field indicates the number of times the “call to action” button will be displayed during the video playtime.
  • Call to Action Duration – This field indicates the duration for which the “call to action” button will be displayed at a particular instance. The values of this field are categorized as small, medium, large. The specifics of the exact duration associated with these values is directly related to the duration of the video uploaded for the Notifications campaign
  • Is Last Slot – This value indicates if the “call to action” button should be displayed at the end of the video. If checked, then the call-to-action button will be displayed at the end of the video. Expected values are true and false.
  • Call to Action Button Text – This piece of information is what the Button will show when displayed offering the viewer an opportunity to go to the Call-to-Action URL.
  • Content Type – This piece of information indicates what type of collateral is being delivered in the notification. Acceptable mediums of collateral and this value can either be “Video” or “Image”.
  • Brand URL – The Enterprise can provide an URL that will be displayed below the campaign video/image in a tab. The Url provided in this field is mostly used as a part of the advertisement which gives the end-user detailed insight into the campaign.
  • Chat URL – This field accepts the chat URL. The chat window will be displayed below the campaign video/image in a tab next to the brand page. The chat URL loads a chatting page which will allow the user to chat with other users who are watching this video at the same time.
  • Is 360 – This piece of information is a Boolean variable, true or false, indicating whether the collateral being onboarded onto the Edge is a 360-degree piece of collateral i.e., 360-degree video
  • Is Campaign Approve – This piece of information is not required. Please leave blank.
  • Campaign Title – The campaign title is a part of the metadata information of the campaign. This title will be displayed when the campaign URL is shared over media applications like WhatsApp, SMS, etc.
  • Campaign Description – The description of the campaign. Campaign description is a part of metadata information of the campaign. This description will be displayed when the campaign URL is shared over media applications like WhatsApp, SMS, etc. 
  • Is Auto Redirect – This piece of information is a Boolean variable, true or false, indicating whether if the end-user should be redirected to the URL provided in the “call to action” field. If checked, then the end-user will be redirected to the “call to action URL” at the end of the video.
  • Default Tab Preference – On the bottom half of the video notification, either the Chat or the Brand URL will be opened based on the preference entered here. This is a mandatory field and the accepted value is either “Brand” or “Chat”.

After adding the parameters to the designated fields, there is no additional input required. Simply click the blue execute button on the bottom of the page. Expected Responses are presented on the Swagger interface. When the user receives a 200 response, they have properly interacted with the API Endpoint.

Get all Campaigns API

The Get All Campaigns Details returns a list of all Campaigns that have been onboarded relevant to a specific Video Notification Subscription. Each item of the list represents a campaign and shares the name, status, approval status, Start and End Time, Total plays to this point, and the click-through rate.

The Parameters of the Add Content to Server API:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

After adding the required parameters, there is no additional input required. Simply click the blue execute button on the bottom of the page. Expected Responses are presented on the Swagger interface. When the user receives a 200 response, they have properly interacted with the API Endpoint.

Get Specific Campaign Status API

The Get Specific Campaign Status API returns the name, status, and approval status for the specified campaign.

The Parameters of the Add Content to Server API:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Campaign Name – This piece of information was provided by the developer during the onboard process.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

After adding the required parameters, there is no additional input required. Simply click the blue execute button on the bottom of the page. Expected Responses are presented on the Swagger interface. When the user receives a 200 response, they have properly interacted with the API Endpoint.

Get Campaign Chart

The Get Campaign Chart API returns information on the campaign name, sms_url, Video ID, Status, Start and End Time, and the renewal of a campaign.

The Parameters of the Add Content to Server API:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

After adding the required parameters, there is no additional input required. Simply click the blue execute button on the bottom of the page. Expected Responses are presented on the Swagger interface. When the user receives a 200 response, they have properly interacted with the API Endpoint.

Delete Specific Campaign API

The Delete Specific Campaign API enables the developer to delete a specific campaign and returns the status and message for the campaign.

The Parameters of the Delete Specific Campaign API:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer EdgeNet” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Campaign Name – This piece of information was provided by the developer during the onboarding process.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

After adding the required parameters, there is no additional input required. Simply click the blue execute button on the bottom of the page. Expected Responses are presented on the Swagger interface. When the user receives a 200 response, they have properly interacted with the API Endpoint.

Developer Curl Script Execution

The following sections of this document will describe interaction with Alef Video Notification API endpoints leveraging the Developer API Curl Scripts across three main areas. The first area is the onboarding of Public Content, the second is the onboarding of private content and the third is additional supporting APIs.

All of these APIs and how to use them through the Swagger User Interface has been explained in the Swagger Documentation UI Execution section. This section will explain how to leverage the Developer Curl Scripts to interact with the Alef APIs. If you have not yet seen the Developer Curl Script document, the URL to the document is: https://developer.alefedge.com/reference-docs/apis-sdks/developer-api-curl-scripts/5g-video-notifications/

Onboard Campaigns

The following workflow permits a Developer to create a Video Notification Campaign where their Cloud Native video or image will be onboarded to the Edge and sent to the designated number of recipients. Once the Developer has onboard the campaign, their video or image collateral will be available to be served from the Edge.

Onboard Campaign

Successfully executing the Onboard Public Content Curl request will be the first step in the workflow to onboard content. The Developer Curl Script for the request is included below. Please note the following pieces of information need to be updated in the Curl script in order to successfully execute:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.
  • Content – This piece of information is the video to be played. The Swagger UI provides a choose file interface in which you can select the video to be onboarded, from your machine.
  • Campaign Name – This piece of information is provided by the Developer and will be the name of the Campaign. This name can be leveraged in future APIs. Please note the name has to be all lowercase characters with a length less than 20.
  • Thumbnail – This piece of information is the photo the Developer wants to represent their video. If the Content is something like a movie trailer, it is likely the thumbnail would be the movie poster.
  • Time ZoneThis piece of information is the time zone in which the campaign is to be executed. It is a decimal value entered by the developer to represent the exact time at the location a campaign is to be started. For example, a campaign that will be executed in New York and to begin based on a New York time will require the value of this field to be -5. Please find the values for some time zones below:
    • -7 – Las Vegas GMT-7:00
    • 5.5 – Mumbai GMT+5:30
    • 3 – Moscow GMT+3:00
    • -5 – New York GMT-5:00
    • -5 – Miami GMT-5:00
    • 5.5 – Pune GMT+5:30 
    • 5.5 – Bangalore GMT+5:30
    • -7 – Santa Clara GMT-7:00
  • Channel Type – This piece of information is the channel in which the notification is to be sent. The options are:
    • SMS – Short Message Service
    • MMS – Multimedia Messaging Service
  • Call to Action URL – This piece of information is not required. If the developer wishes to include it, a Call-to-action URL is the URL which the enterprise can use to target their users.
  • Campaign Start Date – This piece of information is when the developer wants the Notifications Campaign to begin. Please note the format of this information is YYYY-MM-DDTHH:MM:SS
  • Campaign End Date – This piece of information is when the developer wants the Notifications Campaign to end. Please note the format of this information is YYYY-MM-DDTHH:MM:SS
  • SMS Text – This piece of information is the text to be associated with the Notification. It can be a call to action, a message supporting the video or anything else the Developer wants to share.
  • Call to Action Frequency – This field indicates the number of times the “call to action” button will be displayed during the video playtime.
  • Call to Action Duration – This field indicates the duration for which the “call to action” button will be displayed at a particular instance. The values of this field are categorized as small, medium, large. The specifics of the exact duration associated with these values are directly related to the duration of the video uploaded for the Notifications campaign.
  • Is Last Slot – This value indicates if the “call to action” button should be displayed at the end of the video. If checked, then the call-to-action button will be displayed at the end of the video. Expected values are true and false.
  • Call to Action Button Text – This piece of information is what the Button will show when displayed offering the viewer an opportunity to go to the Call-to-Action URL.
  • Content Type – This piece of information indicates what type of collateral is being delivered in the notification. Acceptable mediums of collateral and this value can either be “Video” or “Image”.
  • Brand URL – The Enterprise can provide an URL that will be displayed below the campaign video/image in a tab. The Url provided in this field is mostly used as a part of the advertisement which gives the end-user detailed insight into the campaign.
  • Chat URL – This field accepts the chat URL. The chat window will be displayed below the campaign video/image in a tab next to the brand page. The chat URL loads a chatting page which will allow the user to chat with other users who are watching this video at the same time.
  • Is 360 – This piece of information is a Boolean variable, true or false, indicating whether the collateral being onboarded onto the Edge is a 360-degree piece of collateral i.e., 360-degree video.
  • Is Campaign Approve –This piece of information is not required. Please leave blank.
  • Campaign Title – The campaign title is a part of the metadata information of the campaign. This title will be displayed when the campaign URL is shared over media applications like WhatsApp, SMS, etc.
  • Campaign Description – The description of the campaign. Campaign description is a part of the metadata information of the campaign. This description will be displayed when the campaign URL is shared over media applications like WhatsApp, SMS, etc.
  • Is Auto Redirect – This piece of information is a Boolean variable, true or false, indicating whether if the end-user should be redirected to the URL provided in the “call to action” field. If checked, then the end-user will be redirected to the “call to action URL” at the end of the video.
  • Default Tab Preference – On the bottom half of the video notification, either the Chat or the Brand URL will be opened based on the preference entered here. This is a mandatory field and the accepted value is either “Brand” or “Chat”

Included below is the sample successful response when interacting with the Onboard Campaign Developer Curl Script.

Request

curl -X 'POST' 'https://<domain>/rmn-api/api/v1/rmn/agencies/campaignsOps?partner_name=<partner_name>' -H 'accept: application/json' -H 'api_key: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX' -H 'Content-Type: multipart/form-data' -F 'campaignStartDate=2021-04-20T12:50:00' -F 'callToActionUrl=' -F 'is360=true' -F 'callToActionDuration=small' -F 'smsText=' -F 'brandUrl=https://www.wikipedia.org/' -F 'campaignTitle=www' -F 'campaignDescription=www' -F 'thumbnail=@/home/test/Downloads/test.jpeg;type=image/jpeg' -F 'callToActionFrequency=2' -F 'callToActionButtonText=eee' -F 'defaultTabPreference=' -F 'is_campaign_approve=' -F 'contentType=Video' -F 'isAutoRedirect=true' -F 'chatUrl=https://www.wikipedia.org/' -F 'timeZone=5.5' -F 'content=@/home/test/Downloads/test.mp4;type=video/mp4' -F  'campaignEndDate=2021-05-19T16:40:00' -F 'campaignName=fintestdt' -F 'channelType=SMS' -F 'isLastSlot=true'

Included below is the sample successful response when interacting with the Onboard Campaign Developer Curl Script.

Response

{
   "message": "Campaign onboarding successful. Please check status of campaign dryrun"
}

Check Campaign Status

In order to better understand details surrounding the onboarded Video Notification Campaign, three additional APIs can be leveraged that are detailed below.

Get All Campaigns

Once a campaign or multiple campaigns have been onboarded with respect to a single Video Notification subscription all of the campaign details can be viewed leveraging this API. The Developer Curl Script for the request is included below. Please note the following pieces of information need to be updated in the Curl script in order to successfully execute:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

Included below is the sample successful response when interacting with the Onboard Public Developer Curl Script.

Request

curl --location --request GET 'https://<domain>/rmn-api/api/v1/rmn/agencies/campaignsOps?partner_name=6039f0e85b136c000751aaf3' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api_key: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX' \
--data-raw ''

Included below is the sample successful response when interacting with the Get All Campaigns Developer Curl Script.

Response

[
   {
       "campaign_name": "dryrun",
       "status": "Scheduled",
       "approval_status": "true",
       "start_timestamp": "2021-02-27T07:35:00.000Z",
       "end_timestamp": "2021-03-31T07:35:00.000Z"
   }
]

Get Specific Campaign

If the Developer does not want to see a holistic view and would prefer viewing a specific campaign, the Get Specific Campaign API. The Developer Curl Script for the request is included below. Please note the following pieces of information need to be updated in the Curl script in order to successfully execute:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Campaign Name – This piece of information was provided by the developer during the onboard process.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

Included below is the sample successful response when interacting with the Get Campaign Status Developer Curl Script.

Request

curl --location --request GET 'https://<domain>/rmn-api/api/v1/rmn/agencies/campaigns/status/<campaign_name>?partner_name=6039f0e85b136c000751aaf3' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api_key: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX' \
--data-raw ''

Included below is the sample successful response when interacting with the Get Campaign Status Developer Curl Script.

Response

{
   "campaign_name": "dryrun",
   "status": "Scheduled",
   "approval_status": "true"
}

Get Campaign Chart

If a Developer wants to verify the Edge Content URL while also obtaining some campaign information, the Get Campaign Chart API has been provided. The Developer Curl Script for the request is included below. Please note the following pieces of information need to be updated in the Curl script in order to successfully execute:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer Private Edge” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

Included below is the sample successful response when interacting with the Get Campaign Chart Developer Curl Script.

Request

curl --location --request GET 'https://<domain>/rmn-api/api/v1/rmn/agencies/campaignChart?partner_name=6039f0e85b136c000751aaf3' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api_key: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX' \
--data-raw ''

Included below is the sample successful response when interacting with the Get Campaign Chart Developer Curl Script.

Response

[
   {
       "campaign_name": "dryrun",
       "video_id": "mb",
       "status": "Scheduled",
       "start_timestamp": "2021-02-27T07:35:00.000Z",
       "end_timestamp": "2021-03-31T07:35:00.000Z",
       "renewButton": true,
       "url": "https://<domain>/v1/content?url=e95897528ae5e3d602a078698c1e8babc4d749fed243aa9af335e4f37e5838f918d370fd845f1c2c50540ece14afe33f"
   }
]

Delete Specific Campaign

If the Developer wants to delete a specific campaign that had been onboarded for a particular subscription, the Delete Specific Campaign API has been provided. The Developer Curl Script for the request is included below. Please note the following pieces of information need to be updated in the Curl script in order to successfully execute:

  • API Key – This piece of information was provided to the Developer in their “Welcome to Developer EdgeNet” email, the final step in the Sign-Up process. This information is also accessible via the “My Profile” option from the Account Management Dropdown.
  • Campaign Name – This piece of information was provided by the developer during the onboarding process.
  • Partner Name – This piece of information is provided to the Developer on the Service Management Screen of the subscription being used. It is important to note this field is called “Service ID’ on the Service Management Screen.

Included below is the sample successful request when interacting with the Delete specific Campaign Developer Curl Script.

Request

curl --location --request DELETE 'https://<domain>/rmn-api/api/v1/rmn/agencies/campaigns/<campaign_name>?partner_name=<partner_name>' \
--header 'Content-Type: application/json' \
--header 'api_key: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX' \
--data-raw ''

Included below is the sample successful response when interacting with the Delete specific Campaign Developer Curl Script.

Response

{
   "status": "SUCCESS",
   "message": "Campaign - jello deleted successfully from db"
}

Playing of Content

In order to play content from the Edge, the viewer must be in an Edge Environment. One option for this would be to leverage the Developer Sandbox Container. If you are interested in learning more about how to leverage the sandbox environment, please read this document, <Insert the link to the updated Sandbox Tutorial Document>.

If the user has an Edge Environment in which Edge content can be played. The process in which to play Edge Content there is as follows:

  1. If the Developer has not already done so, onboard a Campaign leveraging the Video Notification Onboard Campaign API
  2. Use the Get Campaign Chart API. From the response obtain the “sms_url”. At the end of the URL, the developer will have to add “&api_key=XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX” to the end (inserting their actual API Key)
  3. Once step three has been completed, the user can take the finalized URL and play it from a browser within the Edge Environment
    • Please note, if the video uploaded is a M3U8 file, it needs to be served from a player and not just a browser. The recommended player for these files is, https://player.stg-alefedge.com/edge. Please ensure https://player.stg-alefedge.com/edge has been added as a whitelisted domain for the content to properly play.
    • For Mac users, it is also important to note, when playing content from the firefox browser, the Content URL must be copied in text formatting (not hyperlinked) using the command and “c” keys. When pasting the Content URL inside the browser, use the control and “v” keys.
    • Finally, once video collateral has been onboarded, there is some lead time before the content is synced to the Edge. The duration of sync depends on the size of the content. For smaller videos, this process may take 2 minutes. For larger videos, this process may take up to 5 minutes.

How useful was this post?

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?