Versions Compared

Old Version 1

changes.mady.by.user sneha.tripathi

Saved on

compared with

New Version 2

changes.mady.by.user sneha.tripathi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


An endpoint is one of the ends of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. Each endpoint is the location from which APIs can access the resources they need to carry out their function. For example, https://lumapro.serviceaide.com/gateway/api/v1.

Following are the various Luma APIs available for Skill developers:

Table of Contents

GetContact

The Luma API GetContact is used to verify if the user exists in Luma and retrieve user details like Display Name, Phone Number, Contact Id. Use the following details to configure and use the Web Service operation for your Skill:

  1. Generate and copy the API Access Token from Luma VA and pass it to the API as the 'Luma-api-access-key' token in the Global Header. Add User Management permission to the API API access key. Refer to Create and Manage API Access Keys to create an API access key with User Management permission.
  2. Fetch the Tenant External ID and pass it to the API as the 'Luma-tenant-externalId' token in the Global Header. Click on the Tenant → Settings. Copy the Tenant External ID on Tenant Information.  Refer to Tenant Information for more details.
    Image Modified 

  3. HTTP Method for the operation: GET

  4. URI: /contacts

  5. Pass the Username provided by the end-user as Query Parameters to the Web Service. 
    Image Modified
  6. As a response, the web service verifies if the user is available in Luma and retrieves user details. In  In Response Configuration: 

    • Verify if no data or error is received.

    • If the user is found, Extract the user details such as registered Phone Number for user validation.

    • Extract the matched user’s Contact ID which will be used to associate the Luma Contact ID to the channel account.

If the user exists, then Luma returns an array of user details. If the ''data'' array returns any value, then it means that a single or multiple users exist in Luma, that align to that data as shown below.

Code Block
{
  "status": "Success",
  "statusCode": 0,
  "statusLine": "Successfully retrieved the contact profile(s).",
  "errors": null,
  "resultData": [
    {
      "href": "/api/v1/contacts/2",
      "id": 2,
      "tenantcontactExternalId": {"8ad83517-2a3d-4075-99d0-888e6b4a5458",
        "hrefuserName": "/api/v1/tenants/1597"John",
        "tenantIdemail": 1597,
 "test@gmail.com",
      "externalIdtitle": null,
        "namefirstName": null"John",
 
      "subDomainlastName": null"Smith",
        "symbolmiddleName": null,
        "statusphone": null "+91 1235667788",     
      "descriptiondisplayName": null,"John Smith"
    }
  ],
  "provisioningDefaultswarnings": null[],
    "timestamp": 1622794112816,
   "subscriptionreasonPhrase": null
      },
   
  "subTenantmetaInfo": {
 
      "hreftotalRecordCount": "/api/v1/subtenants/1",
 
      "idcurrentRecordCount": 1,
     }
}


If the user does not exist, Luma returns an empty ''data'' array as shown below.

Code Block
languagexml
titleSample Response Code Block
linenumberstrue
{
  "tenantstatus": null"Success",
  "statusCode": 0,
    "namestatusLine": null,"Successfully retrieved the    contact profile(s).",
  "descriptionerrors": null,
  "resultData": [],
  "warnings": [],
  "parentSubTenanttimestamp": null1622793185448,
  "reasonPhrase": null,
  },
 "metaInfo": {
    "createdDatetotalRecordCount": "2021-06-04T07:51:36.482Z",
 0,
    "createdByContactcurrentRecordCount": {0
  }
     "href": "/api/v1/contacts/1",
        "id": 1,
        "tenant": null,
        "subTenant": null,
        "createdDate": null,
        "createdByContact": null,
        "modifiedDate": null,
        "modifiedByContact": null,
        "contactExternalId": null,
        "userName": null,
        "email": null,
        "title": null,
        "firstName": null,
        "lastName": null,
        "middleName": null,
        "phone": null,
        "timezone": null,
        "language": null,
        "memberships": [],
        "customAttributes": [],
        "lastUpdatedSourceType": "WEB_UI",
        "lastUpdatedSource": "Bot Builder",
        "displayName": null,
        "conversationCount": 0,
        "recordStatus": {
          "href": null,
          "id": 1,
   }

MapUserToChannelAccount

The Luma API MapUserToChannelAccount API is used to associate the verified contact/user with channel account with appropriate authentication status and mode.

  1. Generate and copy the API Access Token from Luma VA and pass it to the API as the 'Luma-api-access-key' token in the Global Header. Add Bot permission to the API access key. Refer to Create and Manage API Access Keys to create an API access key with Bot permission.
  2. Fetch the Tenant External ID and pass it to the API as the 'Luma-tenant-externalId' token in the Global Header. Click on the Tenant → Settings. Copy the Tenant External ID on Tenant Information.  Refer to Tenant Information for more details.
    Image Added 

  3. HTTP Method for the operation: PUT

  4. URI: /contactchannelauthentication/{channelAccountId}

  5. Pass the Channel account id as Path Parameters to the Web Service. The user's channel account id is available in Channel context variable @{channel.channelAccountId}
    Image Added

  6. Pass the Channel account ID and user's Luma Contact ID as Outbound payload. The contact id is the user's contact id in Luma and is obtained using GetContact API.

    Code Block
    {
  "ccaExternalId": "@{channel.channelAccountId}",
  "authenticationStatus": "SUCCESS",
  "authenticationMode": "MANUAL",
  "contact": {
    "id": @{global.ootb_contact_id}
  }
}


  7. As a response, the web service maps the User id in luma to the Channel account ID  and responds with successful status. The User is now registered in Luma for the specific Chat Channel
Info
titleNote
  1. It is mandatory to pass the user's Contact ID in Luma and Channel Account ID in the request.
  2. To deregister a user for a Channel, update the following details:
    1. Set authenticationStatus to  DEREGISTERED"
    2. Set contact.id to -2

Get Channel Accounts Records 

Luma API Get Channel Account Records is used to retrieve the list of channel accounts for users available in Luma. Add filter conditions to retrieve a refined list of Account Ids. Use the following details to configure and use the Web Service operation for your Skill:

  1. Generate and copy the API Access Token from Luma VA and pass it to the API as the 'Luma-api-access-key' token in the Global Header. Add User Management permission to the API API access key. Refer to Create and Manage API Access Keys to create an API access key with User Management permission.
  2. Fetch the Tenant External ID and pass it to the API as the 'Luma-tenant-externalId' token in the Global Header. Click on the Tenant → Settings. Copy the Tenant External ID on Tenant Information.  Refer to Tenant Information for more details.
    Image Added
  3. Use Get Channel Account Records as Operation Name.
  4. URI: /contactchannelauthentication
  5. HTTP Method for the operation: GET

  6. As a response, the web service generates a list of Channel Account ids available in the tenant. Following is the sample response received from the web service.

    Code Block
    {
  "status": "Success",
  "statusCode": 0,
  "statusLine": "Successfully retrieved the contact channel authentication records",
  "errors": null,
  "resultData": [
    {
      "

...

  1. href": "

...

  1. /api/v1/ContactChannelAuthentication/6",

...

  1. 
      "

...

  1. id":

...

  1. 6,

...

  1. "ccaExternalId": "65dda1f7-697e-4b6a-9899-c503135a41f6",

...

  1. "

...

  1. channelScopeContactId":

...

  1. "02643e4a-ebea-43f4-a115-6d046ed78c9b",
      "

...

  1. channelScopeId": "

...

  1. afafa5d4-20f7-4eca-ad5d-511535de6346",
      "

...

  1. contact": {
        "href": "/api/v1/contacts/

...

  1. 4",
        "id":

...

  1. 4,
        "

...

  1. contactExternalId": null,
        "

...

  1. userName": null,
        "

...

  1. email": null,
        "

...

  1. title": null,
        "

...

  1. firstName": null,
        "

...

  1. lastName": null,
        "

...

  1. middleName": null,
        "

...

  1. phone": null,
        "

...

  1. displayName": null,
        "

...

  1. agentChannel": {

...

  1.          "

...

  1. channelType": null

...

  1.

...

  1. },
        "

...

  1. authenticationStatus":

...

  1. "SUCCESS",
        "

...

  1. authenticationMode": "MANUAL"

...

  1.      }

...

  1.

...

  1. },
    {
      "

...

  1. href":

...

  1. "/api/v1/ContactChannelAuthentication/5",
      "

...

  1. id":

...

  1. 5,

...

  1. 
      "

...

  1. ccaExternalId":

...

  1. "131f5b13-b870-4a14-8784-0f4b2398944c",

...

  1. "

...

  1. channelScopeContactId": "

...

  1. 0a27859e-7429-44de-94cd-08efcbcf2830",

...

  1. "

...

  1. channelScopeId": "

...

  1. afafa5d4-20f7-4eca-ad5d-511535de6346",

...

  1. 
      "

...

  1. contact":

...

  1. {
        "

...

  1. href":

...

  1. "/api/v1/contacts/-2",
        "

...

  1. id":

...

  1. -2,

...

  1. "

...

  1. contactExternalId": null,

...

  1.

...

  1. "

...

  1. userName":

...

  1. null,

...

  1. 
        "

...

  1. email":

...

  1. null,

...

  1. 
        "

...

  1. title": null,

...

  1. "firstName": null,
        "

...

  1. lastName": null,
        "middleName":

...

  1. null,
        "

...

  1. phone":

...

  1. null,
        "

...

  1. displayName":

...

  1. null

...

  1. },
      "

...

  1. agentChannel":

...

  1. {
        "

...

  1. channelType":

...

  1. null

...

  1. },
      "

...

  1. authenticationStatus":

...

  1. "INITIATED",
      "

...

  1. authenticationMode": "

...

  1. MANUAL"

...

  1.

...

  1. },

...

  1.  {

...

  1. 
      "href": "/api/v1/

...

  1. ContactChannelAuthentication/

...

  1. 7",

...

  1. "id":

...

  1. 7,

...

  1. "

...

  1. ccaExternalId":

...

  1. "7ae4c07d-a466-4c9b-a776-e029148f3fe6",
      "

...

  1. channelScopeContactId":

...

  1. "0cfcdda4-64bb-4aeb-a992-b3a53bc36819",
      "

...

  1. channelScopeId":

...

  1. "afafa5d4-20f7-4eca-ad5d-511535de6346",
      "

...

  1. contact":

...

  1. {
        "

...

  1. href":

...

  1. "/api/v1/contacts/-2",
        "

...

  1. id":

...

  1. -2,
        "

...

  1. contactExternalId": null,
        "

...

  1. userName": null,
        "

...

  1. email": null,
        "

...

  1. title": null,
        "firstName":

...

  1. null,
        "

...

  1. lastName":

...

  1. null,
        "

...

  1. middleName":

...

  1. null,
        "

...

  1. phone":

...

  1. null,
        "

...

  1. displayName":

...

  1.  null
      },
      "

...

  1. agentChannel": {

...

  1.

...

  1.        "

...

  1. channelType":

...

  1. null

...

  1. },

...

  1. "

...

  1. authenticationStatus": "

...

  1. INITIATED",

...

  1. 
      "

...

  1. authenticationMode":

...

  1. "MANUAL"
    },

...

  1.  {
      "href":

...

  1. "/api/v1/ContactChannelAuthentication/2",
      "id":

...

  1. 2,
      "

...

  1. ccaExternalId":

...

  1. "5b169c54-6a3c-46a0-ad01-b5f45acce134",

...

  1.    "

...

  1. channelScopeContactId":

...

  1. "372613da-6056-44c7-afa5-f90473ece892",
      "

...

  1. channelScopeId":

...

  1. "afafa5d4-20f7-4eca-ad5d-511535de6346",

...

  1.

...

  1.    "

...

  1. contact": {
        "

...

  1. href":

...

  1. "/api/v1/contacts/2",
        "

...

  1. id":

...

  1. 2,

...

languagexml
titleSample Response Code Block
linenumberstrue

...

  1.       "contactExternalId": null,
        "userName": null,
        "email": null,

...

  1.

...

  1.

...

  1.

...

  1.

...

  1.

...

  1.  "

...

  1. title":

...

  1. null,

...

  1.

...

  1.

...

  1.

...

  1.

...

  1.

...

  1.  "

...

  1. firstName": null,

...

  1.         "

...

  1. lastName":

...

MapUserToChannelAccount

The Luma API MapUserToChannelAccount API is used to associate the verified contact/user with channel account with appropriate authentication status and mode.

...

  1. Generate and copy the API Access Token from Luma VA and pass it to the API as the 'Luma-api-access-key' token in the Global Header. Add Bot permission to the API access key. Refer to Create and Manage API Access Keys to create an API access key with Bot permission.
  2. Fetch the Tenant External ID and pass it to the API as the 'Luma-tenant-externalId' token in the Global Header. Click on the Tenant → Settings. Copy the Tenant External ID on Tenant Information.  Refer to Tenant Information for more details.
    Image Removed 

  3. HTTP Method for the operation: PUT

  4. URI: /contactchannelauthentication/{channelAccountId}

  5. Pass the Channel account id as Path Parameters to the Web Service. The user's channel account id is available in Channel context variable @{channel.channelAccountId}
    Image Removed
    6. Pass the Channel account ID and user's Luma Contact ID as Outbound payload. The contact id is the user's contact id in Luma and is obtained using GetContact API
  6. null,
        "middleName": null,
        "phone": null,
        "displayName": null
      },
      "agentChannel": {
                "channelType": null
      },
      "authenticationStatus": "SUCCESS",
      "authenticationMode": "AUTOMATIC"
      }
  ],
  "warnings": [],
  "timestamp": 1641293230594,
  "reasonPhrase": null,
  "metaInfo": {
    "totalRecordCount": 4,
    "currentRecordCount": 4
  }
}


  7. The User and Channel Account id information is available under resultData. Accessed at the Channel Account Id at path- object .resultData.<record ID>.ccaExternalId.
  8. Add Query Parameters to add additional conditions. You may fetch a filtered list or view more details for a specific section. Following parameter keys can be used:
    1. filter: To filter the records-based details such as contact ID, username.
    2. expand: To get details for a specific section in the response. For example, add expand → Contact to get contact details for the user along with Channel Account ID.

      For example, add the following Query parameters to get Channel Account ID, Contact, and Channel name for a user with username 'test'.
      filter=contact/userName==test&expand=contact,agentChannel
      Image Added
  9. As a response, the web service generates responses based on the additional conditions.
    Code Block
    {
  "
    10. ccaExternalId
  10. status": "
    11. @{channel.channelAccountId}
  11. Success",
  "
    12. authenticationStatus
  12. statusCode":
    13. "SUCCESS"
  13. 0,
  "
    14. authenticationMode
  14. statusLine": "
    15. MANUAL",
  15. Successfully retrieved the
    16. "
  16. contact
    17. ": {
  17.  channel authentication records",
  "errors": null,
  "resultData": [
    {
      "
    18. id
  18. href":
    19. @{global.ootb_contact_id}
  19. "/api/v1/ContactChannelAuthentication/6",
      "id": 6,
    20. } }
  20. As a response, the web service maps the User id luma to the Channel account ID  and responds with successful status. The User is now registered in Luma for the specific Chat Channel

...

titleNote
  1.  "ccaExternalId": "65dda1f7-697e-4b6a-9899-c503135a41f6",
      "channelScopeContactId": "02643e4a-ebea-43f4-a115-6d046ed78c9b",
      "channelScopeId": "afafa5d4-20f7-4eca-ad5d-511535de6346",
      "contact": {
        "href": "/api/v1/contacts/4",
        "id": 4,
        "contactExternalId": "02643e4a-ebea-43f4-a115-6d046ed78c9b",
        "userName": "test",
        "email": "test@serviceaide.com",
        "title": null,
        "firstName": "test",
        "lastName": "test",
        "middleName": null,
        "phone": "9160905020",
        "displayName": "test"
      },
      "agentChannel": {
        "channelType": "TEST_WIDGET"
      },
      "authenticationStatus": "SUCCESS",
      "authenticationMode": "MANUAL"
    }
  ],
  "warnings": [],
  "timestamp": 1641293230594,
  "reasonPhrase": null,
  "metaInfo": {
    "totalRecordCount": 1,
    "currentRecordCount": 1
  }
}