Microsoft Teams API
Telestax Message Exchange for Microsoft Teams helps Communications Providers enable their Business Customers to send and receive SMS using Microsoft Teams and to manage and monitor usage. For more information, access the General Documentation.
This document covers the API(s) that are available to Communications Providers, thus helping to manage Business Customers, users, and mappings while keeping track of usage. If you are interested in managing the mapping via the UI, please access the Microsoft Teams Console documentation that leverages the APIs described here.
| Wherever an API returns a Timestamp or expects Date/Timestamp as a request parameter, the format is given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS±[hh][mm]. For example 2019-10-10T13:13:48+0000. Note that the given date/time is inclusive and is assumed to be in UTC timezone. Hence the offset ±[hh][mm] will always be +0000. |
Business Customer
Communications Providers manage Business Customers. They can create, update, read, and delete Business Customer accounts. The logical grouping of Business Customer accounts under a Communications Provider helps in managing the billing and invoices for the Business Customers.
Business Customer Status
At any given point in time, Business Customers will have one of the following statuses:
-
ACTIVE: Microsoft Teams mappings are operational
-
INACTIVE: Once a Business Customer is marked as INACTIVE
-
All Business Customer Users are marked as INACTIVE and in the Restcomm Platform they will also be marked as INACTIVE.
-
None of the mappings will work.
-
If the status is changed from INACTIVE to ACTIVE, all users in Microsoft Teams and Restcomm will be moved back to ACTIVE.
-
Mappings will start working
-
-
-
CLOSED: Once CLOSED, the status cannot be changed to INACTIVE or ACTIVE.
-
Business Customer users are also CLOSED in the Restcomm Platform.
-
All the mappings are deleted in Microsoft Teams
-
| Eventually once CLOSED all resources associated with the Business Customers will be deleted. However, as of today resources are still kept in the database. |
The following diagram shows the state transition.
Create Business Customer
This endpoint will be used to create a Business Customer in the Microsoft Teams application. Create Business Customer will add unique Business Customer names for given Communications Providers.
Request Parameters
| Parameter | Description |
|---|---|
name |
Mandatory name of the Business Customer. Name must be unique within the given CP Organization. |
status |
Optional. Status of the Business Customer. Default value is ACTIVE. Possible values are ACTIVE and INACTIVE. |
enterpriseAdmin |
Mandatory. Business Customer User data explained in the table below that will be assigned as the admin of this business customer. |
Admin Parameters:
| Business Customer Admin Data Parameter | Description |
|---|---|
name |
Optional. Friendly name of the Business Customer Admin |
emailId |
Mandatory. Business Customer Admin User email ID |
password |
Mandatory. Business Customer Admin password |
| If a new Sub Account being added is already present in Restcomm Core, that Sub Account will now have access to Microsoft Teams however the password will not be changed. |
Response Body
The Response Body will carry Code, corresponding message and data of the Enterprise if it was successfully created. HTTP response will be 201 Created (OK).
The response returned is the JSON body as shown in the example below. Each parameters is explained below
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
User data as explained in the table below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Business Customer ID |
accountSid |
Account Sid of Account that created this particular Business Customer |
accountEmail |
Unique CPaaS Account that created this particular Business Customer |
dateCreated |
Timestamp when this Business Customer was created |
dateUpdated |
Timestamp when this Business Customer was updated |
name |
Name of this Business Customer |
uri |
Unique URI that you can call to get only this specific Business Customer |
status |
Status of the Business Customer as explained in Business Customer Status |
enterpriseAdminEmail |
Email ID of Business Customer Admin |
enterpriseAdminSid |
Account SID of Business Customer Admin user |
Response Parameters
The Create Business Customer API can also return an Error Code and corresponding HTTP Error as mentioned in Common Response Error Codes. In addition below are the errors that it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
4050 |
409 |
Business Customer name not unique |
Add Business Customer API is called with a name that is already present for the organization. There can be the same name of Business Customers in different organizations. |
Create Business Customer, Update Business Customer |
4001 |
409 |
Email not unique |
User already exists |
Create Business Customer, Update Business Customer |
Example
{
"name": "test 101",
"enterpriseAdmin": {
"emailId": "Test101@telestax.com",
"password": "Test@123",
"name": "testU101"
}
}
If creation fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "4050",
"message": "Enterprise name not unique",
"data": {
"data": "test 101"
}
}
From the bash terminal you can run the command below:
curl -X POST \
https://yourdomain.com/msteams/enterprise \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name": "test 101",
"enterpriseAdmin": {
"emailId": "Test101@telestax.com",
"password": "Test@123",
"name": "testU101"
}
}’
If creation of Business Customer is successful, below is the response returned
{
"data": {
"sid": "EN10d5e4b2008945c49696d2128e7dea9f",
"dateUpdated": "2020-11-05T11:59:34+0000",
"dateCreated": "2020-11-05T11:59:34+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/EN10d5e4b2008945c49696d2128e7dea9f",
"name": "test 101",
"status": "ACTIVE",
"enterpriseAdminSid": "RCSddc87ac420074e11b55d44b5f4c2cc47",
"enterpriseAdminEmail": "Test101@telestax.com"
},
"code": 200,
"message": "OK"
}
Update Business Customer
This endpoint will be used to update an existing Business Customer.
Request Parameters
| Parameter | Description |
|---|---|
EnterpriseId |
Mandatory. Business Customer SID that was generated by calling create Business Customer API |
name |
Optional name of Business Customer. Name must be unique within a given CSP Organization. |
Response Body
The Response Body will carry Code, corresponding message, and data of Business Customer account if it was successfully updated. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
User data as explained in the table below. |
Data Parameter
This is explained in Data Parameter of Create Business Customer
Response Parameters
Update Business Customer API can also return an Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, the following are the Errors that it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
4050 |
409 |
Business Customer name not unique |
Add Business Customer API is called with a name that is already present for the Organisation. There can be the same name of Business Customers in different Orgs. |
Create Business Customer, Update Business Customer |
4051 |
409 |
Enterprise not found |
Business Customer SID doesn’t exist in the system |
Update Business Customer,Delete Business Customer,Get Business Customer |
Example
{
"name" : "Kohl"
}
If update of Enterprise fails, corresponding error code and message is returned along with HTTP Error Response
{
"errorCode": "4050",
"message": "Enterprise name not unique",
"data": "kohl"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://yourdomain.com/msteams/enterprises/EN2a9f885831f4a3f935b4a56f296bd9f \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name" : "Kohl"
}’
If update of Business Customer is successful, below is the response returned:
{
"data": {
"sid": "ENe74ac0a9d33f4d9ea8f4e039f7b5af03",
"dateUpdated": "2020-11-05T13:48:18+0000",
"dateCreated": "2020-11-05T12:10:33+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/ENe74ac0a9d33f4d9ea8f4e039f7b5af03",
"name": "Kohl\r\n ",
"status": "ACTIVE",
"enterpriseAdminSid": "RCSf9f08b60c9044cd28ec118ca0387db70",
"enterpriseAdminEmail": "Tes@telestax.com"
},
"code": 200,
"message": "OK"
}
Delete Business Customer
This endpoint will be used to delete an existing Business Customer.
Request Parameters
| Parameter | Description |
|---|---|
EnterpriseSid |
Mandatory. Mandatory. SID to uniquely identify a Business Customer. |
| Deleting a Business Customer will mark status as CLOSED. |
Response Body
Response Body will carry the Code, corresponding message, and data of the Business Customer account if it was successfully deleted. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error, if an error occurred or a success message, if successful. |
data |
User data as explained in the table below. |
Data Parameter
This is explained in Data Parameter of Create Business Customer
Response Parameters
Update Business Customer API can also return an Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, the following are the Errors that it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
4051 |
409 |
Enterprise not found |
Business Customer SID doesn’t exist in the system |
Update Business Customer,Delete Business Customer,Get Business Customer |
409 |
Enterprise has Mappings |
Delete Business Customer API is called for Business customer name that have Mappings associated. |
Delete Business Customer |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://yourdomain.com/msteams/enterprises/EN15fc8edcb9784ec18e91e32bfa0fb1e1\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If delete of Enterprise is successful, below is the response returned:
{
"data": {
"sid": "EN15fc8edcb9784ec18e91e32bfa0fb1e1",
"dateUpdated": "2020-11-06T04:52:10+0000",
"dateCreated": "2020-11-05T16:49:24+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/EN15fc8edcb9784ec18e91e32bfa0fb1e1",
"name": "Test110",
"status": "CLOSED",
"enterpriseAdminSid": "RCSaf32ef5131e741aaae7d35c8318bd5ea",
"enterpriseAdminEmail": "Test110@test.com"
},
"code": 200,
"message": "OK"
}
If delete fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "4051",
"message": "Enterprise not found",
"data": "EN2a9f805831f4a3f935b4a56f296bd9f"
}
Get List of Business Customers
This endpoint will be used to search a list of Business Customers.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Business Customer records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the Search API is called without page and pageSize parameters, by default pageSize will be set to 10 and page will be set to 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
name |
Optional parameter. Only show Business Customers that match the name text, partially or fully. |
Status |
Optional parameter. Only show Business Customers that have this particular status. |
startTime |
Optional parameter. Only show Business Customers that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Business Customers that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. You can sort by the attributes listed below:
Response Body
Response Body will carry Code, corresponding message, and data of the User if it was successfully fetched. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
Parameter |
Description |
data |
Actual data in form of a list that match the filter criteria. Data as explained in "Data Parameter" below. |
numPages |
Number of pages. |
pageSize |
Size of the page. |
total |
Total number of records matching the given criteria. |
page |
Which page of records to return. |
start |
Start offset of the current page. |
end |
Ending offset of the current page. |
firstPageUri |
URI to access the first page. |
previous_page_uri |
URI to access the previous page. |
next_page_uri |
URI to access the next page. |
uri |
URI of the current page. |
Data Parameter
This is explained in Data Parameter of Create Business Customer
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/enterprises/search?pageSize=2&page=0 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"result": [
{
"sid": "ENc9e2179a50aa498e98a2386bcf0b1e10",
"dateUpdated": "2020-11-05T11:32:44+0000",
"dateCreated": "2020-11-05T11:32:43+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/ENc9e2179a50aa498e98a2386bcf0b1e10",
"name": "ent1",
"status": "ACTIVE",
"enterpriseAdminSid": "RCS8c73a988119744879f808741b9dd1977",
"enterpriseAdminEmail": "ent123@telestax.com"
},
{
"sid": "EN10d5e4b2008945c49696d2128e7dea9f",
"dateUpdated": "2020-11-05T11:59:35+0000",
"dateCreated": "2020-11-05T11:59:35+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/EN10d5e4b2008945c49696d2128e7dea9f",
"name": "test 101",
"status": "ACTIVE",
"enterpriseAdminSid": "RCSddc87ac420074e11b55d44b5f4c2cc47",
"enterpriseAdminEmail": "Test101@telestax.com"
},
{
"sid": "ENe74ac0a9d33f4d9ea8f4e039f7b5af03",
"dateUpdated": "2020-11-05T14:00:54+0000",
"dateCreated": "2020-11-05T12:10:33+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/ENe74ac0a9d33f4d9ea8f4e039f7b5af03",
"name": "Kohl",
"status": "INACTIVE",
"enterpriseAdminSid": "RCSf9f08b60c9044cd28ec118ca0387db70",
"enterpriseAdminEmail": "Tes@telestax.com"
},
{
"sid": "ENfcbda46695394523bc34cd99f6b5ebee",
"dateUpdated": "2020-11-05T12:42:33+0000",
"dateCreated": "2020-11-05T12:42:31+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/ENfcbda46695394523bc34cd99f6b5ebee",
"name": "test 1001",
"status": "ACTIVE",
"enterpriseAdminSid": "RCS17d566d923eb4093886068224fb4d4c8",
"enterpriseAdminEmail": "test1001@telestax.com"
}
],
"pageSize": 10,
"total": 4,
"page": 0,
"numPages": 1,
"start": 0,
"end": 3,
"firstPageUri": "/msteams/enterprises/search/?pageSize=10&page=0",
"uri": "/msteams/enterprises/search/?pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Business Customer
Single Business Customer search API allows users to retrieve specific Business Customers.
Request Parameters
| Parameter | Description |
|---|---|
EnterpriseId |
Mandatory SID to uniquely identify a Business Customer. |
Response Body
Response Body will carry the Code, corresponding message, and data of the User if it was successfully searched. HTTP response will be 200 OK.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
4051 |
409 |
Enterprise not found |
Business Customer SID doesn’t exist in the system. |
Update Business Customer,Delete Business Customer,Get Business Customer |
The response returned is JSON body as shown in the example below. Parameters are as explained below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error if error occurred or success message if successful. |
data |
User data as explained in the table below. |
Data Parameter
This is explained in Data Parameter of Create Business Customer
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/enterprises/search/EN86b7850af05a454b95139d59ca420849 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "EN8d661fa8ba7d4acd8ff7cf3039ef9552",
"dateUpdated": "2020-11-06T16:40:03+0000",
"dateCreated": "2020-11-06T16:40:00+0000",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/enterprises/search/EN8d661fa8ba7d4acd8ff7cf3039ef9552",
"name": "BotApp",
"status": "ACTIVE",
"enterpriseAdminSid": "RCSa1be1c1578bd452587eeb90ef9f740db",
"enterpriseAdminEmail": "Bot@bot.com"
},
"code": 200,
"message": "OK"
}
If it fails, the following response is returned.
{
"errorCode": "4051",
"message": "Enterprise not found",
"data": "EN8d661fa8ba7d4acd8ff7cf3039ef95"
}
Manage Mappings
There is always a mapping associated with a Business Customer.
Create Microsoft Teams Mappings
Create Microsoft Teams Mapping will add a mapping between a Microsoft Teams user ID and an SMS enabled number.
Supported Operations
HTTP POST: SMS enable a number and create a mapping between Microsoft Teams users and a phone number.
Request Parameters
| Parameter | Description |
|---|---|
name |
Optional friendly name of Microsoft Teams user. If not passed it is the same as the Microsoft Teams UserID. |
microsoftAddress |
Mandatory Microsoft Teams User ID to be mapped. |
externalAddress |
Mandatory number that must be mapped with userID. The system will also SMS enable this number. This must be unique in the whole system. |
enterpriseSid |
Mandatory Enterprise ID that was added via Create Business Customer API call. |
Response Body
The Response Body will carry the Code, corresponding message and data of Mapping if it was successfully created. HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occurred or success message |
data |
User data as explained in the table below. |
Mapping Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Microsoft Teams mapping ID. |
enterpriseSid |
Business Customer ID under which this Mapping is created. |
enterpriseName |
Name of Business Customer under which this Mapping is created. |
accountSid |
Unique Restcomm Account that created/updated this particular Business Customer. |
accountEmail |
Email associated with accountSID. |
dateCreated |
Timestamp when this Mapping was created. |
dateUpdated |
Timestamp when this Mapping was updated. |
name |
Friendly name of this user. |
microsoftAddress |
Microsoft Teams user ID. |
externalAddress |
SMS enabled number mapped to this Microsoft Teams ID. |
uri |
Unique URI that you can call to get only this specific mapping SDR. |
Response Parameters
The Create Microsoft Teams mapping API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
482 |
409 |
externalAddress not unique |
externalAddress is already in use. |
Create Mapping, Update Mapping |
4051 |
409 |
Enterprise not found |
Business Customer for which mapping is to be added is not found. |
Create Mapping, Update Mapping |
485 |
409 |
Microsoft Address is not Valid |
The Microsoft Teams address/ID which was passed for mapping is not valid. The Application tries to validate the Microsoft Teams ID with the Bot details provided and only if the Microsoft Teams ID belongs to the same Organization for which the Bot was created, mapping is allowed. |
Create Mapping |
Example
{
"name" : "sunny",
"microsoftAddress" : "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"externalAddress" : "9090919196768998",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065"
}
From the bash terminal you can run the command below:
curl -X POST \
https://yourdomain.com/msteams/teams/mappings\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name" : "sunny",
"microsoftAddress" : "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"externalAddress" : "9090919196768998",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065"
}’
If creation of mapping is successful, below is the response returned:
{
"data": {
"sid": "BEcf981df3576a47afbc927a7230bc9c28",
"dateUpdated": "Fri Nov 06 09:44:33 UTC 2020",
"dateCreated": "Fri Nov 06 09:44:33 UTC 2020",
"accountSid": "ACf2e8e8dbf16e2849604e0b8e6ff4c169",
"accountEmail": "bta@tele.com",
"uri": "/msteams/teams/mappings/search/BEcf981df3576a47afbc927a7230bc9c28",
"microsoftAddress": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"externalAddress": "9090919196768998",
"name": "sunny",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"enterpriseName": "mac"
},
"code": 200,
"message": "OK"
}
If creation of mapping fails, below is the response returned. Exact error code and message will depend on error occurred
{
"errorCode": "482",
"message": " externalAddress not unique",
"data": "9090919196768998"
}
Update Microsoft Teams Mappings
Update Microsoft Teams Mapping will update mapping between the Microsoft Teams user ID and the SMS enabled number.
Request Parameters
| Parameter | Description |
|---|---|
mappingId Mandatory unique mapping ID that was generated by calling Add Mapping API. |
name |
Optional friendly name of Microsoft Teams user. If not passed it’s the same as jabberAddress record. |
microsoftAddress |
Optional. Microsoft Teams User ID to be mapped. |
enterpriseId |
Response Body
Response Body will carry the Code, corresponding message and data of Mapping. If it was successfully Updated, HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error if error occurred or success message. |
data |
Mappings data as explained in the table Mapping Data Parameter. |
Response Parameters
Update Microsoft Teams Mapping API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
409 |
Enterprise not found |
Business Customer for which mapping is to be added is not found. |
Create Mapping, Update Mapping, |
|
480 |
409 |
Mapping id not found |
Update is called passing Mapping ID that is not found for the Organization. |
Update Mapping |
Example
{
"name" : "Mapping11"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://yourdomain.com/msteams/teams/mappings/BEa0e3d44bd03947eaa3fbb783a3bc31dd \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name" : "Mapping 11"
}’
If update of mapping is successful, below is the response returned:
{
"data": {
"sid": "BEa0e3d44bd03947eaa3fbb783a3bc31dd",
"dateUpdated": "2020-11-11 17:28:28.0",
"dateCreated": "2020-11-11 17:28:28.0",
"accountSid": "ACd3041c25343ae31412f7068df12db54f",
"accountEmail": "solutiondev1@telestax.com",
"uri": "/msteams/teams/mappings/search/BEa0e3d44bd03947eaa3fbb783a3bc31dd",
"microsoftAddress": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"externalAddress": "998713777011",
"name": "sunny11",
"enterpriseSid": "EN9dbb06d89ff24f3eacd7ee0cf141c3e2",
"enterpriseName": "Entfinal"
},
"code": 200,
"message": "OK"
}
If update of mapping fails, corresponding error code and message will be returned with HTTP Error code.
{
"errorCode": "4050",
"message": "Enterprise name not unique",
"data": "kohl"
}
Delete Mapping
Delete Mapping will delete mapping between the Microsoft Teams user and the SMS enabled number.
Supported Operations
HTTP DELETE: Delete mapping between the Microsoft Teams users and the SMS enabled number.
Request Parameters
| Parameter | Description |
|---|---|
mappingId |
Unique Mapping ID that was generated by calling the Add Mapping API. |
Response Body
Response Body will carry the Code, corresponding message, and data of the Mapping that is deleted. If it was successfully deleted, HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Mappings data as explained in the table Mapping Data Parameter |
Response Parameters
Delete Microsoft Teams Mapping API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
480 |
409 |
Mapping not found |
MappingID is not found for the Organization. |
Update Mapping, Delete Mapping, Search Mapping |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://yourdomain.com/msteams/mappings/BEfbacbc4979564f32802cc9f284600b84\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If delete mapping is successful, below is the response returned:
{
"data": {
"sid": "BEfbacbc4979564f32802cc9f284600b84",
"dateUpdated": "2020-11-06 12:06:22.0",
"dateCreated": "2020-11-06 12:06:22.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/teams/mappings/search/BEfbacbc4979564f32802cc9f284600b84",
"microsoftAddress": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"externalAddress": "9091909192",
"name": "map111",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"enterpriseName": "mac"
},
"code": 200,
"message": "OK"
}
If delete of mapping fails, corresponding error code and message will be returned with HTTP Error code.
{
"errorCode": "480",
"message": "Mapping Id not found",
"data": "BEfbacc4979564f32802cc9f284600b84"
}
Get list of Microsoft Teams Mappings
List Microsoft Teams Mappings API allows users to list all the Mappings for a specific organization which means under that Communications Provider.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Business Customer records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the Search API is called without page and pageSize parameters, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
The following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
EnterpriseSid |
Optional parameter to show all mappings under that Enterprise ID. |
startTime |
Optional parameter. Only show Business Customers that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Business Customers that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
name |
Optional parameter. Only show mappings that match name text, partially or fully. |
microsoftAddress |
Optional parameter. Only show mappings that match Microsoft Teams user ID text, partially or fully. |
externalAddress |
Optional parameter. Only show mappings that match externalAddress text, partially or fully. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. You can sort by the attributes listed below:
Sort Attributes
| Parameter | Description |
|---|---|
name |
Sort by name |
dateCreated |
Sort by created date |
microsoftAddress |
Sort by Microsoft Teams user |
externalAddress |
Sort by external Address |
domain |
Sort by domain name |
Response Body
Response Body will carry the Code, corresponding message, and data of the Mappings if it was successfully fetched. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each Parameter is explained below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error if error occurred or success message. |
data |
User data as explained in the table below. |
Parameter |
Description |
result |
Mapping data as explained in the result table below. |
pageSize |
Number of records returned per page. |
total |
Total number of records matching the given criteria. |
page |
Which page of records to return. |
numPages |
Total number of pages. |
start |
Starting offset of page. |
end |
Ending offset of page. |
firstPageUri |
Unique URI that you can call to get records on the First page. |
next_page_uri |
Unique URI that you can call to get records on the next page. |
uri |
Unique URI that you can call to get records. |
Result Parameter
This is explained in Data Parameter of Mapping data Parameter of create mapping.
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/teams/mappings/search \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"result": [
{
"sid": "BE7c6b0bd04a92495096102b326336bb32",
"dateUpdated": "2020-11-06 11:27:44.0",
"dateCreated": "2020-11-06 11:27:44.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/teams/mappings/search/BE7c6b0bd04a92495096102b326336bb32",
"microsoftAddress": "subhahu@solutionstelestax.onmicrosoft.com",
"externalAddress": "989898909090",
"name": "map1",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"enterpriseName": "mac"
},
{
"sid": "BE66acb763396d40e3a534a496b2b488c6",
"dateUpdated": "2020-11-06 11:29:44.0",
"dateCreated": "2020-11-06 11:29:18.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/teams/mappings/search/BE66acb763396d40e3a534a496b2b488c6",
"microsoftAddress": "subhahu@solutionstelestax.onmicrosoft.com",
"externalAddress": "989898909091",
"name": "map3",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"enterpriseName": "mac"
}
],
"pageSize": 10,
"total": 2,
"page": 0,
"numPages": 1,
"start": 0,
"end": 1,
"firstPageUri": "/msteams/teams/mappings/search/?pageSize=10&page=0",
"uri": "/msteams/teams/mappings/search/?pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Microsoft Teams Mapping
Single Mapping Search API allows users to retrieve a specific mapping created under that organisation which means under that Communications Provider.
Response Parameters
Search Microsoft Teams mapping API will return the Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
480 |
409 |
Mapping not found |
Mapping ID is not found for the Organization |
Update Mapping, Delete Mapping, Search Mapping |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/mappings/search/BE7c6b0bd04a92495096102b326336bb32\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "BE7c6b0bd04a92495096102b326336bb32",
"dateUpdated": "2020-11-06 11:27:44.0",
"dateCreated": "2020-11-06 11:27:44.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "aditya.dixit@telestax.com",
"uri": "/msteams/teams/mappings/search/BE7c6b0bd04a92495096102b326336bb32",
"microsoftAddress": "subhahu@solutionstelestax.onmicrosoft.com",
"externalAddress": "989898909090",
"name": "map1",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"enterpriseName": "mac"
},
"code": 200,
"message": "OK"
}
Bot Details
Create Bot Details
For Microsoft Teams users to be able to receive incoming SMS on the Microsoft Teams Client and to be able to send outbound SMS, the following parameters should be collected from Business Customers as explained in the documentation here. These parameters must be set up for each of the Business Customers defined in Create Business Customer via API below.
-
Application ID
-
Tenant ID
-
Client Secret
-
Bot App ID
Request Parameters
| Parameter | Description |
|---|---|
applicationId |
Mandatory. Application ID which is generated by creating application in Azure. |
tenantId |
Mandatory. TenantID for Application above. |
clientSecret |
Mandatory. ClientSecret which is generated while creating application in Azure |
botAppId |
Mandatory.Bot App ID is APP store ID which is generated after publishing the bot app. |
enterpriseSid |
Mandatory Enterprise ID that was added via Create Business Customer API call. |
Response Body
The Response Body will carry the Code, corresponding message and data of Mapping if it was successfully created. HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occurred or success message |
data |
User data as explained in the table below. |
Bot details Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Microsoft Teams mapping ID. |
enterpriseSid |
Business Customer ID under which this Mapping is created. |
enterpriseName |
Name of Business Customer under which this Mapping is created. |
accountSid |
Unique Restcomm Account that created/updated this particular Business Customer. |
accountEmail |
Email associated with accountSID. |
dateCreated |
Timestamp when this Mapping was created. |
dateUpdated |
Timestamp when this Mapping was updated. |
applicationId |
Application ID of Business Customer. |
tenantId |
Tenant ID of Business Customer. |
clientSecret |
Client Secret of the enterprise. |
botAppId |
App store ID of Business Customer Bot. |
uri |
Unique URI that you can call to get only this specific Bot access. |
Response Parameters
Create Microsoft Teams mapping API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
4051 |
409 |
Enterprise not found |
Business Customer for which bot details are to be added is not found. |
Create Bot details, Update Bot details Update Bot details |
Example
{
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "dc46be1e-fc19-428c-974d-cacc29308ec1",
"tenantId": "7dc79737-6ed7-40b3-98f2-e190c33d9172",
"clientsecret": "VMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7137e37c-2443-46bf-89fc-883b2bb6b9b3"
}
From the bash terminal you can run the command below:
curl -X POST \
https://yourdomain.com/mxteams/teamsbot/details\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "dc46be1e-fc19-428c-974d-cacc29308ec1",
"tenantId": "7dc79737-6ed7-40b3-98f2-e190c33d9172",
"clientsecret": "VMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7137e37c-2443-46bf-89fc-883b2bb6b9b3"
}’
If creation of mapping is successful, below is the response returned:
{
"data": {
"sid": "BEf571c41e2b654c77bf6d9fc2de5931e0",
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "dc46be1e-fc19-428c-974d-cacc29308ec1",
"clientsecret": "VMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7137e37c-2443-46bf-89fc-883b2bb6b9b3"
},
"code": 200,
"message": "OK"
}
{
"errorCode": "4051",
"message": "Enterprise not found",
"data": "EN97154a1491a44f3afe05880bcc1f147"
}
Update Bot Details
This endpoint is used to update Bot details.
Request Parameters
| Parameter | Description |
|---|---|
BotSid |
Mandatory. Bot SID that was generated by calling create Bot details API. |
applicationId |
Optional. Application ID which is generated by creating application in Azure. |
tenantId |
Optional. Organization ID for that Enterprise in Azure. |
clientSecret |
Optional. ClientSecret which is generated while creating application in Azure . |
botAppId |
Optional.Bot App Id is APP store id which is generated after publishing the bot app. |
enterpriseId |
Optional. EnterpriseID that was added via Create Business Customer API call. |
Response Body
Response Body will carry the Code, corresponding message and data of Bot details if it was successfully Updated, HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error if error occured or success message. |
data |
Bot details data as explained in the table below. |
Bot Details Data Parameter
This is explained in Bot Details Data Parameter of Create Bot Details.
Response Parameters
Update Bot details API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
4051 |
409 |
Enterprise not found |
Business Customer for which Bot details are to be added is not found. |
Create Bot details, Update Bot details Update Bot details |
481 |
409 |
There is no Details added for this Bot |
Update is called passing BotSID that is not found for the given Organization. |
Update Bot details,Delete Bot details. |
Example
{
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "db36be1e-fc19-428c-974d-cacc29308ec1",
"tenantId": "7bc78737-6ed7-40b3-98f2-e190c33d9172",
"clientsecret": "XMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7156e37c-2443-46bf-89fc-883b2bb6b9b3"
}
From the bash terminal you can run the command below:
curl -X POST \
https://yourdomain.com/mxteams/teamsbot/details/BE0aa557177fe64a1ab5fc84e329c6066a\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "db36be1e-fc19-428c-974d-cacc29308ec1",
"tenantId": "7bc78737-6ed7-40b3-98f2-e190c33d9172",
"clientsecret": "XMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7156e37c-2443-46bf-89fc-883b2bb6b9b3"
}’
If update of mapping is successful, below is the response returned:
{
"data": {
"sid": "BE0aa557177fe64a1ab5fc84e328d6066a",
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "db36be1e-fc19-428c-974d-cacc29308ec1",
"clientsecret": "XMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7156e37c-2443-46bf-89fc-883b2bb6b9b3"
},
"code": 200,
"message": "OK"
}
If update of mapping fails, corresponding error code and message will be returned with HTTP Error code.
{
"errorCode": "481",
"message": "There is no Details added for this Bot",
"data": "BE0aa55717fe64a1ab5fc84e328d6066a"
}
Delete Bot Details
Delete Mapping will delete mapping between the Microsoft Teams user and the SMS enabled number.
Request Parameters
| Parameter | Description |
|---|---|
BotSid |
Bot SID that was generated by calling create Bot details API. |
Response Body
Response Body will carry the Code, corresponding message, and data of Bot details that are deleted.If it was successfully deleted, HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error if error occured or success message. |
data |
Bot details data as explained in the table below. |
Bot details Data Parameter
This is explained in Bot Details Data Parameter of Create Bot Details.
Response Parameters
Delete Bot API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
481 |
409 |
There is no Details added for this Bot |
Update is called passing BotSID that is not found for the given Organization. |
Update Bot details |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://yourdomain.com/msteams/teamsbot/details/BE0aa557177fe64a1ab5fc84e329c6066a\ --user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If delete Bot details Api is successful, below is the response returned:
{
"data": {
"sid": "BE0aa557177fe64a1ab5fc84e328d6066a",
"enterpriseSid": "EN97154a1c491a44f3afe05880bcc1f147",
"applicationId": "db36be1e-fc19-428c-974d-cacc29308ec1",
"clientsecret": "XMwpRjv9983y3-nLISs~...tx7e7kyaX_l",
"botAppId": "7156e37c-2443-46bf-89fc-883b2bb6b9b3"
},
"code": 200,
"message": "OK"
}
If delete of the Bot details Api fails, corresponding error code and message will be returned with HTTP Error code.
{
"errorCode": "481",
"message": "There is no Details added for this Bot",
"data": "BE0aa555177fe64a1ab5fc84e328d6066a"
}
Get List of Bot Details
List Bot details API allows users to list all the Bot details for specific organization which means under that Communications Provider.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Business Customer records to return, starting from 0. |
pageSize |
Number of records returned per page. |
| If search API is called without page and pageSize parameters, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
The following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
EnterpriseSid |
Optional parameter to show all Bots under that Enterprise ID |
startTime |
Optional parameter. Only show Business Customers that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Business Customers that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Sort by the attributes listed below:
Response Parameters
Delete Bot API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code
The response returned is JSON body as shown in the example below. Each Parameter is explained below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response. |
message |
Message describing error if error occurred or success message. |
data |
Data of search as explained in the table below. |
Data parameters
Parameter |
Description |
result |
This is explained in Data Parameter in Bot details data parameters of Create Bot Details. |
pageSize |
Number of records returned per page. |
total |
Total number of records. |
page |
Which page of records to return. |
numPages |
Total number of pages |
start |
Starting offset of page. |
end |
Ending offset of page. |
firstPageUri |
Unique URI that you can call to get records on the first page. |
next_page_uri |
Unique URI that you can call to get records on the next page. |
uri |
Unique URI that you can call to get records. |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/teamsbot/details/search \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"result": [
{
"sid": "BE183b20b0d27441c7849712b6417de1f2",
"enterpriseSid": "ENfcbda46695394523bc34cd99f6b5ebee",
"applicationId": "dc46be1e-fc19-428c-853c-cacc29308ec1",
"clientsecret": "VMwpRjv9983y4-nLISs~...tu7e7kyaX_l",
"botAppId": "7154e27c-2423-46af-89fc-883b2bb6b9b2"
},
{
"sid": "BE33c9d4b18dd0427ea4f11bb5a4b1ce24",
"enterpriseSid": "ENe74ac0a9d33f4d9ea8f4e039f7b5af03",
"applicationId": "dc46be1e-fc19-428c-853c-cacc29308ec1",
"clientsecret": "VMwpRjv9983y4-nLISs~...tu7e7kyaX_l",
"botAppId": "7154e27c-2423-46af-89fc-883b2bb6b9b2"
},
{
"sid": "BE6cbadd7326f244a49b46097a50e91e3a",
"enterpriseSid": "EN6a1a3e424623478ab6afb5db1cbd9964",
"applicationId": "3edc1deb-8070-4506-8d5e-8cb0d40814d6",
"clientsecret": "-h476O9J-hlo0X1~I_a7oUY746t_ynhcz4",
"botAppId": "718e2b8b-9fc3-48b3-9ad5-2fd738cc2d9a"
},
{
"sid": "BE702c3901032649ac9e5d4f56c9b804db",
"enterpriseSid": "ENc9e2179a50aa498e98a2386bcf0b1e10",
"applicationId": "12345",
"clientsecret": "234234",
"botAppId": "23423424"
},
{
"sid": "BE733c4343e45e47a88297e4c5627df506",
"enterpriseSid": "EN9dbb06d89ff24f3eacd7ee0cf141c3e2",
"applicationId": "3edc1deb-8070-4506-8d5e-8cb0d40814d6",
"clientsecret": "-h476O9J-hlo0X1~I_a7oUY746t_ynhcz4",
"botAppId": "718e2b8b-9fc3-48b3-9ad5-2fd738cc2d9a"
},
{
"sid": "BE9a0b02490b1b4b6eb22790f503cc9358",
"enterpriseSid": "EN7027a7a0998a4488bf03c4f8951cba3b",
"applicationId": "3edc1deb-8070-4506-8d5e-8cb0d40814d6",
"clientsecret": "-h476O9J-hlo0X1~I_a7oUY746t_ynhcz4",
"botAppId": "c526826c-e510-49e1-ab76-2095b33464f2"
},
{
"sid": "BEa2eb5b3f1d8f4d3c96b48a071f29a31a",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"applicationId": "dc46be1e-fc19-428c-853c-cacc29308ec1",
"clientsecret": "VMwpRjv9983y4-nLISs~...tu7e7kyaX_l",
"botAppId": "7154e27c-2423-46af-89fc-883b2bb6b9b2"
}
],
"pageSize": 10,
"total": 7,
"page": 0,
"numPages": 1,
"start": 0,
"end": 6,
"firstPageUri": "/msteams/teamsbot/details/search/?pageSize=10&page=0",
"uri": "/msteams/teamsbot/details/search/?pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Bot Details
The Single Bot Details search API allows users to retrieve specific Bot details created under that organisation which means under that Communications Provider.
Request Parameters
| Parameter | Description |
|---|---|
BotSid |
Bot SID that was generated by calling create Bot details API. |
Response Parameters
Search Bot details API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
481 |
409 |
There is no Details added for this Bot |
Update is called passing BotSID that is not found for the given Organization. |
Update Bot details,Delete Bot details,Get Bot details |
Data parameters
This is explained in Data Parameter in Bot Details Data Parameters of Create Bot Details.
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/teamsbot/search/BE733c4343e45e47a88297e4c5627df506\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "BE733c4343e45e47a88297e4c5627df506",
"enterpriseSid": "EN9dbb06d89ff24f3eacd7ee0cf141c3e2",
"applicationId": "3edc1deb-8070-4506-8d5e-8cb0d40814d6",
"clientsecret": "-h476O9J-hlo0X1~I_a7oUY746t_ynhcz4",
"botAppId": "718e2b8b-9fc3-48b3-9ad5-2fd738cc2d9a"
}
,
"code": 200,
"message": "OK"
}
Messages
Get List of Messages
List Message API allows users to list all the Messages for specific Organization which means under that Communications Provider.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Business Customer records to return, starting from 0. |
pageSize |
Number of records returned per page. |
| If the search API is called without page and pageSize parameters, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
EnterpriseSid |
Optional parameter to show all messages under that Enterprise ID. |
startTime |
Optional parameter. Only show messages that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show messages that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
type |
Optional parameter. Only show messages that match type. Possible values are: |
direction |
Optional parameter. Only show messages that match direction .Possible values are * inbound * outbound |
from |
Only show messages that have from begins with this number or Jabber Address text.For example, if a message from is "15713316943" and from filter parameter is "1", it will match. However if from filter parameter is "3", this record will not match. |
to |
Only show messages that have to begin with this number or Jabber Address ID text. For example, if a message to is "16513333367" and to filter parameter is "1", it will match. However if to filter parameter is "3", this record will not match. |
channelStatus |
Optional parameter. Only show messages that match channelStatus text, partially or fully. |
channelErrorCode |
Optional parameter. Only show messages that match channelErrorCode text, partially or fully. |
channelErrorMessage |
Optional parameter. Only show messages that match channelErrorMessage text, partially or fully |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. You can sort by the attributes listed below:
Sort Attributes
| Parameter | Description |
|---|---|
dateCreated |
Sort by date when the message was created. |
from |
Sort by from. |
to |
Sort by to. |
Response Body
The response returned is JSON body as shown in the example below. Each parameters are as explained below
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Data of search as explained in table below |
Data Parameter
| Parameter | Description |
|---|---|
result |
Message data as explained in the table below. |
pageSize |
Number of records returned per page. |
total |
Total number of records matching the given criteria. |
page |
Which page of records to return. |
numPages |
Total number of pages. |
start |
Start offset of the current page. |
end |
Ending offset of the current page. |
firstPageUri |
Unique URI that you can call to get records on the First page. |
next_page_uri |
Unique URI that you can call to get records on the next page. |
uri |
Unique URI that you can call to get records. |
Response Parameters
| Response Parameter | Description |
|---|---|
sid |
Unique Message ID. |
enterpriseSid |
Business Customer ID under which this Message is created. |
accountSid |
Unique Restcomm Account that created/updated this particular message. |
dateCreated |
Timestamp when this Message was created. |
dateUpdated |
Timestamp when this Message was updated. |
direction |
Direction of this message. Possible values are: |
from |
From Which number or Microsoft Teams ID this message is sent |
to |
To which number or Microsoft Teams ID this message is sent |
uri |
Unique URI that you can call to get only this specific message SDR. |
restcommMessageSid |
Target SID of the message. |
channelStatus |
Channel status of message. |
channelErrorCode |
Channel error code of the message. |
channelErrorMessage |
Channel error message of the message. |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/messages/search \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"result": [
{
"sid": "MS1089b2c7692d4fc1babf452ad9eb008a",
"dateUpdated": "2020-11-09 08:06:00.0",
"dateCreated": "2020-11-09 08:06:00.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "887789876765",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
},
{
"sid": "MSc4d2b1b5102e4e6990e6167039aa5c55",
"dateUpdated": "2020-11-09 08:06:28.0",
"dateCreated": "2020-11-09 08:06:28.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "887789876765",
"to": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"direction": "OUTBOUND",
"type": "SMS",
"channelStatus": "QUEUED"
},
{
"sid": "MS2dbd567530844457a477c43991cd01df",
"dateUpdated": "2020-11-09 11:10:42.0",
"dateCreated": "2020-11-09 11:10:42.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "12345432134",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
},
{
"sid": "MS68cbc2c59add480289660f34cb44d4e5",
"dateUpdated": "2020-11-09 11:11:21.0",
"dateCreated": "2020-11-09 11:11:21.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "12345432134",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
},
{
"sid": "MSbd3c221be9df4f16b40763d6988b6574",
"dateUpdated": "2020-11-09 11:12:24.0",
"dateCreated": "2020-11-09 11:12:24.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "56566565",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
},
{
"sid": "MS4084365be46246d9b8a151361471a5a5",
"dateUpdated": "2020-11-09 11:13:25.0",
"dateCreated": "2020-11-09 11:13:25.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "56566565",
"to": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"direction": "OUTBOUND",
"type": "SMS",
"channelStatus": "QUEUED"
},
{
"sid": "MSe4f1823cd87d41fcaf9e215e670d663b",
"dateUpdated": "2020-11-09 11:18:00.0",
"dateCreated": "2020-11-09 11:18:00.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "56566565",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
},
{
"sid": "MS09ca14265e424875850371b441f767db",
"dateUpdated": "2020-11-09 11:19:05.0",
"dateCreated": "2020-11-09 11:19:05.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "56566565",
"to": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"direction": "OUTBOUND",
"type": "SMS",
"channelStatus": "QUEUED"
},
{
"sid": "MS7532b424c0554bc1963ac24b3549d3e7",
"dateUpdated": "2020-11-09 11:20:02.0",
"dateCreated": "2020-11-09 11:20:02.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "56566565",
"to": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"direction": "OUTBOUND",
"type": "SMS",
"channelStatus": "QUEUED"
},
{
"sid": "MS51c630e28e2744bb83677048e1b1c7ae",
"dateUpdated": "2020-11-09 11:48:17.0",
"dateCreated": "2020-11-09 11:48:17.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "56566565",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
}
],
"pageSize": 10,
"total": 14,
"page": 0,
"numPages": 2,
"start": 0,
"end": 10,
"firstPageUri": "/msteams/messages/search/?pageSize=10&page=0",
"nextPageUri": "/msteams/messages/search/?pageSize=10&page=1",
"uri": "/msteams/messages/search/?pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Message
Single message search API allows users to retrieve a specific message created under that organisation which means under that Communications Provider.
Response Parameters
Search Bot details API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
481 |
409 |
Message Id not found |
API is called passing Message Id that is not present in system |
Search Message |
Data parameters
This is explained in Data Parameter in Data Parameters of GET List of messages.
Example
From the bash terminal you can run the command below:
curl -X GET \
https://yourdomain.com/msteams/messages/search/MS51c630e28e28e2744bb83677048e1b1c7ae \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "MS51c630e28e2744bb83677048e1b1c7ae",
"dateUpdated": "2020-11-09 11:48:17.0",
"dateCreated": "2020-11-09 11:48:17.0",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"enterpriseSid": "EN7d19fdad67914d91965b231cf706c065",
"from": "sunnydodhiya@solutionstelestax.onmicrosoft.com",
"to": "56566565",
"direction": "INBOUND",
"type": "SMS",
"channelStatus": "DELIVERED"
},
"code": 200,
"message": "OK"
}
If GET call for single search message fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "481",
"message": "Message Id not found",
"data": "MS1c630e28e2744bb83677048e1b1c7ae"
}