Luma APIs for User Registration

Owned by sneha.tripathi
Last updated: Feb 12, 2024 by Kishore Surisetty
8 min read

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:

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.
     

  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. 
  6. As a response, the web service verifies if the user is available in Luma and retrieves user details. 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.

{
  "status": "Success",
  "statusCode": 0,
  "statusLine": "Successfully retrieved the contact profile(s).",
  "errors": null,
  "resultData": [
    {
      "href": "/api/v1/contacts/2",
      "id": 2,
      "contactExternalId": "8ad83517-2a3d-4075-99d0-888e6b4a5458",
      "userName": "John",
      "email": "test@gmail.com",
      "title": null,
      "firstName": "John",
      "lastName": "Smith",
      "middleName": null,
      "phone": "+91 1235667788",     
      "displayName": "John Smith"
    }
  ],
  "warnings": [],
  "timestamp": 1622794112816,
  "reasonPhrase": null,
  "metaInfo": {
    "totalRecordCount": 1,
    "currentRecordCount": 1
  }
}


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

Sample Response Code Block
{
  "status": "Success",
  "statusCode": 0,
  "statusLine": "Successfully retrieved the contact profile(s).",
  "errors": null,
  "resultData": [],
  "warnings": [],
  "timestamp": 1622793185448,
  "reasonPhrase": null,
  "metaInfo": {
    "totalRecordCount": 0,
    "currentRecordCount": 0
  }
}

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.
     

  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}

  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.

    {
  "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

Note

  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.
  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.

    {
  "status": "Success",
  "statusCode": 0,
  "statusLine": "Successfully retrieved the contact channel authentication records",
  "errors": null,
  "resultData": [
    {
      "href": "/api/v1/ContactChannelAuthentication/6",
      "id": 6,
      "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": null,
        "userName": null,
        "email": null,
        "title": null,
        "firstName": null,
        "lastName": null,
        "middleName": null,
        "phone": null,
        "displayName": null,
        "agentChannel": {
          "channelType": null
        },
        "authenticationStatus": "SUCCESS",
        "authenticationMode": "MANUAL"
      }
    },
    {
      "href": "/api/v1/ContactChannelAuthentication/5",
      "id": 5,
      "ccaExternalId": "131f5b13-b870-4a14-8784-0f4b2398944c",
      "channelScopeContactId": "0a27859e-7429-44de-94cd-08efcbcf2830",
      "channelScopeId": "afafa5d4-20f7-4eca-ad5d-511535de6346",
      "contact": {
        "href": "/api/v1/contacts/-2",
        "id": -2,
        "contactExternalId": null,
        "userName": null,
        "email": null,
        "title": null,
        "firstName": null,
        "lastName": null,
        "middleName": null,
        "phone": null,
        "displayName": null
      },
      "agentChannel": {
        "channelType": null
      },
      "authenticationStatus": "INITIATED",
      "authenticationMode": "MANUAL"
    },
    {
      "href": "/api/v1/ContactChannelAuthentication/7",
      "id": 7,
      "ccaExternalId": "7ae4c07d-a466-4c9b-a776-e029148f3fe6",
      "channelScopeContactId": "0cfcdda4-64bb-4aeb-a992-b3a53bc36819",
      "channelScopeId": "afafa5d4-20f7-4eca-ad5d-511535de6346",
      "contact": {
        "href": "/api/v1/contacts/-2",
        "id": -2,
        "contactExternalId": null,
        "userName": null,
        "email": null,
        "title": null,
        "firstName": null,
        "lastName": null,
        "middleName": null,
        "phone": null,
        "displayName": null
      },
      "agentChannel": {
          "channelType": null
      },
      "authenticationStatus": "INITIATED",
      "authenticationMode": "MANUAL"
    },
    {
      "href": "/api/v1/ContactChannelAuthentication/2",
      "id": 2,
      "ccaExternalId": "5b169c54-6a3c-46a0-ad01-b5f45acce134",
      "channelScopeContactId": "372613da-6056-44c7-afa5-f90473ece892",
      "channelScopeId": "afafa5d4-20f7-4eca-ad5d-511535de6346",
      "contact": {
        "href": "/api/v1/contacts/2",
        "id": 2,
        "contactExternalId": null,
        "userName": null,
        "email": null,
        "title": null,
        "firstName": null,
        "lastName": 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

  9. As a response, the web service generates responses based on the additional conditions.

    {
  "status": "Success",
  "statusCode": 0,
  "statusLine": "Successfully retrieved the contact channel authentication records",
  "errors": null,
  "resultData": [
    {
      "href": "/api/v1/ContactChannelAuthentication/6",
      "id": 6,
      "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": "0123456789",
        "displayName": "test"
      },
      "agentChannel": {
        "channelType": "TEST_WIDGET"
      },
      "authenticationStatus": "SUCCESS",
      "authenticationMode": "MANUAL"
    }
  ],
  "warnings": [],
  "timestamp": 1641293230594,
  "reasonPhrase": null,
  "metaInfo": {
    "totalRecordCount": 1,
    "currentRecordCount": 1
  }
}

© 2019 Serviceaide 1-650-206-8988 http://www.serviceaide.com info@serviceaide.com