From f2c724683fac0b749cc253b80f34430e914d6d37 Mon Sep 17 00:00:00 2001 From: Crispin Koech Date: Thu, 19 Nov 2020 06:56:43 +0300 Subject: [PATCH] Update Africa's Talking SMS Connector; Add Airtime and Voice Connector. (#563) * Update Africa's Talking Payments connector * Include host policy instances to Africa's Talking payments connector * Fix typo * Add sanbox Athena option in list of providers * Update SendSMS parameters; remove empty paths in payments connector * Update Africa's Talking Payment's Icon. * Add webhooks to Africa's Talking SMS * Add Africa's Talking Airtime * Add Africa's Talking Voice * Undo color change * Update status code descriptions and api info Co-authored-by: Crispin Kipruto --- .../Africa's Talking Airtime/README.md | 31 ++ .../apiDefinition.swagger.json | 303 ++++++++++++++++++ .../apiProperties.json | 35 ++ .../Africa's Talking SMS/README.md | 8 +- .../apiDefinition.swagger.json | 259 +++++++++++++++ .../Africa's Talking SMS/apiProperties.json | 14 + .../Africa's Talking Voice/README.md | 25 ++ .../apiDefinition.swagger.json | 211 ++++++++++++ .../Africa's Talking Voice/apiProperties.json | 23 ++ 9 files changed, 908 insertions(+), 1 deletion(-) create mode 100644 certified-connectors/Africa's Talking Airtime/README.md create mode 100644 certified-connectors/Africa's Talking Airtime/apiDefinition.swagger.json create mode 100644 certified-connectors/Africa's Talking Airtime/apiProperties.json create mode 100644 certified-connectors/Africa's Talking Voice/README.md create mode 100644 certified-connectors/Africa's Talking Voice/apiDefinition.swagger.json create mode 100644 certified-connectors/Africa's Talking Voice/apiProperties.json diff --git a/certified-connectors/Africa's Talking Airtime/README.md b/certified-connectors/Africa's Talking Airtime/README.md new file mode 100644 index 000000000..dfabdf3e7 --- /dev/null +++ b/certified-connectors/Africa's Talking Airtime/README.md @@ -0,0 +1,31 @@ +## Africa's Talking Airtime + +Africa's Talking Airtime offers a power API that allows you to distribute pinless airtime to mobile subscribers, receiving discounts for each transaction you make. This connector exposes operations that enable one to send airtime to mobile subscribers as well as to watch for notifications indicating whether the delivery was successful or failed. + +## Pre-requisites + +In order to use this connector, you will need the following: + +* An account with Africa's Talking; you can sign up [here](https://account.africastalking.com/auth/register?next=%2Fauth%2Fsignup). +* A live production application; you can create one after registering. + +Once you've signed up and you've created a live application, generate a new API Key for that application; you will use this key to authenticate your requests from this connector. + +You will also need to contact us to activate the airtime product for your application; do so by sending an email to airtime@africastalking.com. + +## Authentication. + +This connector uses `API Key` authentication (see steps above on how to obtain one). When creating a new connector (in Power Apps/Logic Apps), you'll be required to provide an API Key. + +## Supported Operations + +This connector supports the following operations: + +* `Send Airtime`: Send airtime to multiple recipients. +* `Find transaction status`: Find a particular airtime transaction's status. + +It also supports the following triggers: + +* `When you receive an Airtime Status Notification`: Triggered when you receive an delivery status notification for an initial request to send airtime. + +For more information on parameters accepted/required by the connector's operations, please refer to our [documentation](https://developers.africastalking.com/docs/airtime/overview). diff --git a/certified-connectors/Africa's Talking Airtime/apiDefinition.swagger.json b/certified-connectors/Africa's Talking Airtime/apiDefinition.swagger.json new file mode 100644 index 000000000..3ea386d8a --- /dev/null +++ b/certified-connectors/Africa's Talking Airtime/apiDefinition.swagger.json @@ -0,0 +1,303 @@ +{ + "swagger": "2.0", + "info": { + "title": "Africa's Talking Airtime", + "description": "Provides actions to distribute airtime to your users instantly via Africa's Talking's Airtime service and to watch for status notifications regarding these airtime requests", + "version": "1.0", + "contact": { + "name": "Advice and answers from the Africa's Talking Team", + "url": "https://help.africastalking.com/en/", + "email": "airtime@africastalking.com" + } + }, + "host": "api.africastalking.com", + "basePath": "/", + "schemes": [ + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/version1/airtime/send": { + "post": { + "responses": { + "201": { + "description": "201", + "schema": { + "type": "object", + "properties": { + "errorMessage": { + "type": "string", + "description": "errorMessage" + }, + "numSent": { + "type": "integer", + "format": "int32", + "description": "numSent" + }, + "responses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "type": "string", + "description": "amount" + }, + "discount": { + "type": "string", + "description": "discount" + }, + "errorMessage": { + "type": "string", + "description": "errorMessage" + }, + "phoneNumber": { + "type": "string", + "description": "phoneNumber" + }, + "requestId": { + "type": "string", + "description": "requestId" + }, + "status": { + "type": "string", + "description": "status" + } + } + }, + "description": "responses" + }, + "totalAmount": { + "type": "string", + "description": "totalAmount" + }, + "totalDiscount": { + "type": "string", + "description": "totalDiscount" + } + } + } + } + }, + "summary": "Send Airtime", + "description": "Send airtime to multiple recipients", + "operationId": "SendAirtime", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "Content-Type", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "Accept", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "Your application's username.", + "title": "Username", + "x-ms-visibility": "important" + }, + "recipients": { + "type": "array", + "items": { + "type": "object", + "properties": { + "phoneNumber": { + "type": "string", + "description": "Phone number to be topped up in international format (e.g +234811222333)", + "title": "Phone Number", + "x-ms-visibility": "important" + }, + "amount": { + "type": "string", + "description": "The value of airtime to send together with the currency code (e.g. KES 10.00).", + "title": "Amount", + "x-ms-visibility": "important" + } + }, + "required": [ + "amount", + "phoneNumber" + ] + }, + "description": "recipients" + } + }, + "x-ms-visibility": "important", + "required": [ + "recipients", + "username" + ] + }, + "x-ms-visibility": "important" + } + ] + } + }, + "/query/transaction/find": { + "get": { + "responses": { + "200": { + "description": "Send airtime request successfully queued", + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "status" + } + } + } + } + }, + "summary": "Find transaction status", + "description": "Find a particular airtime transaction's status", + "operationId": "FindTransactionStatus", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "username", + "in": "query", + "required": true, + "type": "string", + "description": "Your application's username", + "x-ms-summary": "Username", + "x-ms-visibility": "important" + }, + { + "name": "transactionId", + "in": "query", + "required": true, + "type": "string", + "description": "ID of the transaction you'd like to find.", + "x-ms-summary": "Transaction ID", + "x-ms-visibility": "important" + } + ] + } + }, + "/api/v1/powerapps/{username}/airtime/status/callback": { + "x-ms-notification-content": { + "schema": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "requestId" + }, + "status": { + "type": "string", + "description": "status" + } + } + }, + "description": "A new airtime delivery status notification" + }, + "post": { + "responses": { + "200": { + "description": "Airtime Notification webhook created successfully" + } + }, + "summary": "When you receive an Airtime Status Notification", + "description": "Triggered when you receive an delivery status notification for an initial request to send airtime.", + "operationId": "AirtimeStatusNotification", + "x-ms-visibility": "important", + "x-ms-trigger": "single", + "parameters": [ + { + "name": "username", + "in": "path", + "required": true, + "type": "string", + "description": "Your application's username", + "x-ms-summary": "Username", + "x-ms-visibility": "important", + "x-ms-url-encoding": "single" + }, + { + "name": "Content-Type", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "url", + "title": "", + "x-ms-visibility": "internal", + "x-ms-notification-url": true + } + }, + "x-ms-visibility": "internal", + "required": [ + "url" + ] + }, + "x-ms-visibility": "internal" + } + ] + } + } + }, + "x-ms-connector-metadata": [ + { + "propertyName": "Website", + "propertyValue": "https://africastalking.com/airtime" + }, + { + "propertyName": "Privacy policy", + "propertyValue": "https://africastalking.com/privacy_policy" + }, + { + "propertyName": "Categories", + "propertyValue": "Communication;Finance" + } + ], + "definitions": {}, + "parameters": {}, + "responses": {}, + "securityDefinitions": { + "API Key": { + "type": "apiKey", + "in": "header", + "name": "apiKey" + } + }, + "security": [ + { + "API Key": [] + } + ], + "tags": [] +} \ No newline at end of file diff --git a/certified-connectors/Africa's Talking Airtime/apiProperties.json b/certified-connectors/Africa's Talking Airtime/apiProperties.json new file mode 100644 index 000000000..e0fef137f --- /dev/null +++ b/certified-connectors/Africa's Talking Airtime/apiProperties.json @@ -0,0 +1,35 @@ +{ + "properties": { + "connectionParameters": { + "api_key": { + "type": "securestring", + "uiDefinition": { + "displayName": "API Key", + "description": "The API Key for this api", + "tooltip": "Provide your API Key", + "constraints": { + "tabIndex": 2, + "clearText": false, + "required": "true" + } + } + } + }, + "policyTemplateInstances": [ + { + "templateId": "dynamichosturl", + "title": "Replace webhook triggers host url", + "parameters": { + "x-ms-apimTemplateParameter.urlTemplate": "https://account.africastalking.com", + "x-ms-apimTemplate-operationName": [ + "AirtimeStatusNotification" + ] + } + } + ], + "iconBrandColor": "#fc9206", + "capabilities": [], + "publisher": "Africa's Talking", + "stackOwner": "Africa's Talking" + } +} \ No newline at end of file diff --git a/certified-connectors/Africa's Talking SMS/README.md b/certified-connectors/Africa's Talking SMS/README.md index c13d7fd18..322c92f60 100644 --- a/certified-connectors/Africa's Talking SMS/README.md +++ b/certified-connectors/Africa's Talking SMS/README.md @@ -22,4 +22,10 @@ This connector supports the following operations: * `Send SMS`: Send a text message to multiple mobile recipients. * `Fetch Inbox`: Fetch messages from your application's inbox. -For more information on parameters accepted/required by the connector's operations, please refer to our [documentation](https://build.at-labs.io/docs/sms%2Foverview). +It also supports the following triggers: + +* `When you receive a Delivery Report for a sent message`: Triggered when you receive a Delivery Report for a message initially sent. +* `When you receive a message in your inbox`: Triggered whenever a message is sent to any of your registered shortcodes. +* `When a number opts out of receiving your bulk messages`: Triggered whenever a user opts out of receiving messages from your alphanumeric sender ID. + +For more information on parameters accepted/required by the connector's operations, please refer to our [documentation](https://developers.africastalking.com/docs/sms/overview). diff --git a/certified-connectors/Africa's Talking SMS/apiDefinition.swagger.json b/certified-connectors/Africa's Talking SMS/apiDefinition.swagger.json index 9c3255947..a4412483f 100644 --- a/certified-connectors/Africa's Talking SMS/apiDefinition.swagger.json +++ b/certified-connectors/Africa's Talking SMS/apiDefinition.swagger.json @@ -210,6 +210,265 @@ }, "x-ms-visibility": "important" } + }, + "/api/v1/powerapps/{username}/sms/dlr/callback": { + "x-ms-notification-content": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "id" + }, + "status": { + "type": "string", + "description": "status" + }, + "phoneNumber": { + "type": "string", + "description": "phoneNumber" + }, + "networkCode": { + "type": "string", + "description": "networkCode" + }, + "failureReason": { + "type": "string", + "description": "failureReason" + }, + "retryCount": { + "type": "integer", + "format": "int32", + "description": "retryCount" + } + } + }, + "headers": { + "Content-type": { + "description": "Content-type", + "type": "string" + } + }, + "description": "A new delivery report for a message" + }, + "post": { + "responses": { + "200": { + "description": "Delivery Notification Webhook created successfully" + } + }, + "summary": "When you receive a Delivery Report for a sent message", + "description": "Triggered when you receive a Delivery Report for a message initially sent", + "operationId": "DlrNotification", + "x-ms-visibility": "important", + "x-ms-trigger": "single", + "parameters": [ + { + "name": "username", + "in": "path", + "required": true, + "type": "string", + "x-ms-visibility": "important", + "x-ms-url-encoding": "single", + "x-ms-summary": "Username", + "description": "Your application's username." + }, + { + "name": "Content-Type", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "url", + "x-ms-visibility": "internal", + "title": "", + "x-ms-notification-url": true + } + }, + "x-ms-visibility": "internal", + "required": [ + "url" + ] + }, + "x-ms-visibility": "internal" + } + ] + } + }, + "/api/v1/powerapps/{username}/sms/inbox/callback": { + "x-ms-notification-content": { + "schema": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "date" + }, + "from": { + "type": "string", + "description": "from" + }, + "id": { + "type": "string", + "description": "id" + }, + "linkId": { + "type": "string", + "description": "linkId" + }, + "text": { + "type": "string", + "description": "text" + }, + "to": { + "type": "string", + "description": "to" + }, + "networkCode": { + "type": "string", + "description": "networkCode" + } + } + }, + "description": "A new message in your inbox" + }, + "post": { + "responses": { + "200": { + "description": "Inbox Notification Webhook created successfully" + } + }, + "summary": "When you receive a message in your inbox", + "description": "Triggered whenever a message is sent to any of your registered shortcodes", + "operationId": "InboxNotification", + "x-ms-visibility": "important", + "x-ms-trigger": "single", + "parameters": [ + { + "name": "username", + "in": "path", + "required": true, + "type": "string", + "description": "Your application's username", + "x-ms-summary": "Username", + "x-ms-visibility": "important", + "x-ms-url-encoding": "single" + }, + { + "name": "Content-Type", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "url", + "title": "", + "x-ms-visibility": "internal", + "x-ms-notification-url": true + } + }, + "x-ms-visibility": "internal", + "required": [ + "url" + ] + }, + "x-ms-visibility": "internal" + } + ] + } + }, + "/api/v1/powerapps/{username}/sms/optout/callback": { + "x-ms-notification-content": { + "description": "A bulk sms opt out notification", + "schema": { + "type": "object", + "properties": { + "senderId": { + "type": "string", + "description": "senderId" + }, + "phoneNumber": { + "type": "string", + "description": "phoneNumber" + } + } + } + }, + "post": { + "responses": { + "200": { + "description": "BulkSMS Optout Webhook created successfully" + } + }, + "summary": "When a number opts out of receiving your bulk messages", + "description": "Triggered whenever a user opts out of receiving messages from your alphanumeric sender ID", + "operationId": "BulkSMSOptOutNotification", + "x-ms-visibility": "important", + "x-ms-trigger": "single", + "parameters": [ + { + "name": "username", + "in": "path", + "required": true, + "type": "string", + "x-ms-visibility": "important", + "x-ms-summary": "Username", + "description": "Your Application's username", + "x-ms-url-encoding": "single" + }, + { + "name": "Content-Type", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "url", + "title": "", + "x-ms-visibility": "internal", + "x-ms-notification-url": true + } + }, + "x-ms-visibility": "internal", + "required": [ + "url" + ] + }, + "x-ms-visibility": "internal" + } + ] + } } }, "x-ms-connector-metadata": [ diff --git a/certified-connectors/Africa's Talking SMS/apiProperties.json b/certified-connectors/Africa's Talking SMS/apiProperties.json index 517343a83..dda404e7d 100644 --- a/certified-connectors/Africa's Talking SMS/apiProperties.json +++ b/certified-connectors/Africa's Talking SMS/apiProperties.json @@ -15,6 +15,20 @@ } } }, + "policyTemplateInstances": [ + { + "templateId": "dynamichosturl", + "title": "Replace webhook triggers host url", + "parameters": { + "x-ms-apimTemplateParameter.urlTemplate": "https://account.africastalking.com", + "x-ms-apimTemplate-operationName": [ + "DlrNotification", + "InboxNotification", + "BulkSMSOptOutNotification" + ] + } + } + ], "iconBrandColor": "#fc9206", "capabilities": [], "publisher": "Africa's Talking", diff --git a/certified-connectors/Africa's Talking Voice/README.md b/certified-connectors/Africa's Talking Voice/README.md new file mode 100644 index 000000000..9fd9c34c9 --- /dev/null +++ b/certified-connectors/Africa's Talking Voice/README.md @@ -0,0 +1,25 @@ +## Africa's Talking Voice + +Africa's Talking Voice offers a powerful API to build dynamic, scalable, fully-featured voice applications that reside entirely in the cloud without the need to purchase and maintain expensive voice equipment. This connector offers an operation to initiate a call to multiple recipients, providing a couple of voice actions that specify how the call should be handled. + +## Pre-requisites + +In order to use this connector, you will need the following: + +* An account with Africa's Talking; you can sign up [here](https://account.africastalking.com/auth/register?next=%2Fauth%2Fsignup). +* A live production application; you can create one after registering. +* A live phone number on this application; you can request for one by sending an email to voice@africastalking.com + +Once you've signed up and you've created a live application, generate a new API Key for that application; you will use this key to authenticate your requests from this connector. + +## Authentication. + +This connector uses `API Key` authentication (see steps above on how to obtain one). When creating a new connector (in Power Apps/Logic Apps), you'll be required to provide an API Key. + +## Supported Operations + +This connector supports the following operations: + +* `Call`: Make an outbound call to multiple recipients. For now, this operation only supports two voice *actionTypes*: `Say` and `Play`. + +For more information on parameters accepted/required by the connector's operations, please refer to our [documentation](https://developers.africastalking.com/docs/voice/overview). diff --git a/certified-connectors/Africa's Talking Voice/apiDefinition.swagger.json b/certified-connectors/Africa's Talking Voice/apiDefinition.swagger.json new file mode 100644 index 000000000..f61fe23b8 --- /dev/null +++ b/certified-connectors/Africa's Talking Voice/apiDefinition.swagger.json @@ -0,0 +1,211 @@ +{ + "swagger": "2.0", + "info": { + "title": "Africa's Talking Voice", + "description": "Offers an action to schedule outbound calls to recipients through Africa's Talking's Voice API. You can use this connector to instruct our Voice service to Say/Play a sequence of items in an outbound call.", + "version": "1.0", + "contact": { + "name": "Advice and answers from the Africa's Talking Team", + "url": "https://help.africastalking.com/en/", + "email": "voice@africastalking.com" + } + }, + "host": "voice.africastalking.com", + "basePath": "/", + "schemes": [ + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/call": { + "post": { + "responses": { + "201": { + "description": "201", + "schema": { + "type": "object", + "properties": { + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "phoneNumber": { + "type": "string", + "description": "phoneNumber" + }, + "status": { + "type": "string", + "description": "status" + }, + "sessionId": { + "type": "string", + "description": "sessionId" + } + } + }, + "description": "entries" + }, + "errorMessage": { + "type": "string", + "description": "errorMessage" + } + } + } + } + }, + "summary": "Make an outbound call", + "description": "Make an outbound call to multiple recipients", + "operationId": "Call", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "Content-Type", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "Accept", + "in": "header", + "required": true, + "type": "string", + "default": "application/json", + "x-ms-visibility": "internal" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "Your application's username", + "title": "Username", + "x-ms-visibility": "important" + }, + "from": { + "type": "string", + "description": "Your Africa's Talking phone number, in international format.", + "title": "From", + "x-ms-visibility": "important" + }, + "to": { + "type": "array", + "items": { + "type": "string", + "description": "Recipient phone number", + "title": "To", + "x-ms-visibility": "important" + }, + "description": "to" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "actionType": { + "type": "string", + "description": "An action for our voice service to perform in this call", + "title": "Action", + "x-ms-visibility": "important", + "enum": [ + "Play", + "Say" + ] + }, + "text": { + "type": "string", + "description": "Text that will be read out to the recipient of the call", + "title": "Text", + "x-ms-visibility": "advanced" + }, + "url": { + "type": "string", + "description": "A valid URL that contains a link to an audio file to be played", + "title": "Url", + "x-ms-visibility": "advanced" + }, + "voice": { + "type": "string", + "description": "Voice to use to read out the text sent with this request", + "title": "Voice", + "x-ms-visibility": "advanced", + "enum": [ + "man", + "woman" + ] + }, + "playBeep": { + "type": "boolean", + "description": "Play a beep after reading out the text contained in this request", + "title": "Play Beep", + "x-ms-visibility": "advanced", + "enum": [ + true, + false + ] + } + }, + "required": [ + "actionType" + ] + }, + "description": "actions" + } + }, + "x-ms-visibility": "important", + "required": [ + "from", + "username", + "to", + "actions" + ] + }, + "x-ms-visibility": "important" + } + ] + } + } + }, + "x-ms-connector-metadata": [ + { + "propertyName": "Website", + "propertyValue": "https://africastalking.com/voice" + }, + { + "propertyName": "Privacy policy", + "propertyValue": "https://africastalking.com/privacy_policy" + }, + { + "propertyName": "Categories", + "propertyValue": "Communication" + } + ], + "definitions": {}, + "parameters": {}, + "responses": {}, + "securityDefinitions": { + "API Key": { + "type": "apiKey", + "in": "header", + "name": "apiKey" + } + }, + "security": [ + { + "API Key": [] + } + ], + "tags": [] +} \ No newline at end of file diff --git a/certified-connectors/Africa's Talking Voice/apiProperties.json b/certified-connectors/Africa's Talking Voice/apiProperties.json new file mode 100644 index 000000000..517343a83 --- /dev/null +++ b/certified-connectors/Africa's Talking Voice/apiProperties.json @@ -0,0 +1,23 @@ +{ + "properties": { + "connectionParameters": { + "api_key": { + "type": "securestring", + "uiDefinition": { + "displayName": "API Key", + "description": "The API Key for this api", + "tooltip": "Provide your API Key", + "constraints": { + "tabIndex": 2, + "clearText": false, + "required": "true" + } + } + } + }, + "iconBrandColor": "#fc9206", + "capabilities": [], + "publisher": "Africa's Talking", + "stackOwner": "Africa's Talking" + } +} \ No newline at end of file