# Vocalize

Vocalize is an AI-powered voice [gamification tool](https://www.infobip.com/docs/ai-hub/ai-gamification) in which end users repeat a configured phrase by following specific instructions. The more closely their response matches the instructions, the higher their score.

## How Vocalize works [#how-vocalize-works]

### How gamification works [#how-it-works-gamification]

End users repeat the configured phrase by following the specified instructions and aligning with the displayed image.

AI scores their voice response based on similarity to the phrase and image. The closer the response is to the phrase and the instructions, the higher their score. The score is then added to a leaderboard, enabling the end users to track their performance against others.

You can also offer prizes for top ranks.

### User interaction flow [#how-it-works-user-interaction-flow]

End users can interact with the Vocalize tool through an Infobip solution such as an Answers chatbot.

1. An end user contacts your WhatsApp chatbot.
2. The chatbot invites them to play a game.
3. If the end user agrees to play, the chatbot asks them for basic details such as name and company.
4. The chatbot saves this information in People in either a new or existing Person profile as applicable.
5. The chatbot asks the end user to say the configured phrase and provides instructions.
6. The end user sends a voice message containing the phrase.
7. The chatbot uses AI to score how close the end user's message is to the configured phrase and the instructions.
8. The chatbot sends feedback to the end user and includes their score in a leaderboard.

### Example [#how-it-works-example]

The phrase is: *I love Berlin.*

The instructions are: *Record a voice message saying I love Berlin, but it should resemble the Berlin skyline.*

An image of the Berlin skyline is displayed to guide the end user.

The end user repeats this phrase and uses vocal pitch, rhythm, and pauses to resemble the peaks, dips, and spaces in the Berlin skyline.

## How to use Vocalize [#how-to-use-vocalize]

1. [Create a Vocalize campaign](#create-campaign-in-postman) through Postman.
2. To make the campaign available to end users, add it to an [Answers chatbot](#use-vocalize-in-chatbot).

## Create a Vocalize campaign through Postman [#create-campaign-in-postman]

Create a campaign that uses Vocalize.

### Prerequisites [#create-in-postman-prerequisites]

- **Vocalize**: Enable **Vocalize** in your Infobip account. For more information, contact your Infobip account manager.
- **API keys**: The following API keys:
  - Valid WhatsApp API key with all the WhatsApp scopes enabled. Create the key in the [**Infobip web interface**](https://portal.infobip.com/login) and enable the scopes.
  - Valid API key with the **vocalize:manage** scope enabled. Create the key in the [**Infobip web interface**](https://portal.infobip.com/login). To enable the scope, contact your Infobip account manager.

        For information about creating API keys, refer to the [API scopes](https://www.infobip.com/docs/essentials/api-essentials/api-authorization#api-scope-configuration-api-scopes) documentation.

- **Keyword**: Determine the keyword or phrase to use in the campaign. Example: *I love Infobip.*
- **API builder**: [Postman](https://www.postman.com/) to send requests to the Vocalize API.

### Prepare the image [#create-in-postman-prepare-image]

Prepare the image to use in the campaign. For Vocalize to work, the image must follow these guidelines:

- The image must have a white background and black foreground.
- The object must be at the center of the image.
- For the best results, the image must be symmetrical.
- Image must be in .png or .jpeg format.

The following are examples of the types of images:

- City skylines
- Mountain or canyon ridgelines
- Forest edges and tree lines
- Ocean waves, sand dunes, glacier crests
- Human-made shapes on the horizon such as cranes, wind turbine farms, roller coasters
- Rows of everyday objects such as books or bottles on a shelf, LEGO bricks

The following are examples of images:

Image of a mountain range

Image of a tree line

Image of a city skyline

### Create the campaign [#create-in-postman-process]

1. Use the following template to create a Vocalize campaign.

    [Download the template](https://infobip-cdn-h0h7ekhqhgh4hgau.a02.azurefd.net/1g8x60m5haaeebc38sw9etdnqwq2orfxs6yjtxwklw767cqz71/Vocalize_Create_Campaign_JSON.postman_collection.json)

2. Import the template in Postman.
3. Go to the template that you imported.
4. In the **Overview** tab, enter a description for the campaign.
5. Select the **Create new campaign** endpoint.
6. In the **Auth** tab, complete the following fields:
   - **Type**: Select **API key**.
   - **Key**: Enter a key. Example: *Authorization*.
   - **Value**: Enter the value of the Vocalize API key that you created. Use the following format: `App <your-vocalize-api-key>`.
7. In the **Body** tab, update the existing JSON with information about your campaign. Update only the content that is indicated by square brackets [].

    For more information about the parameters, refer to the [Create a new campaign](https://www.infobip.com/docs/api/ai/vocalize/vocalize-create-campaign) API documentation.
8. To trigger the API call, select **Send**.

You should get an `HTTP 201` status code that indicates that the campaign has been created. The response body contains the parameters of the campaign.

The **id** parameter contains the campaign ID in UUID format. This ID is required to use the campaign in your chatbot.

## Use the Vocalize campaign with an Answers chatbot [#use-vocalize-in-chatbot]

To make your Vocalize campaign accessible to end users, use it in an Answers chatbot.

Follow one of these options:

- **[Use a template](#create-chatbot-through-template)**: Use a template to create the chatbot.
- **[Create manually](#create-chatbot-manually)**: Create the chatbot manually.

### Use a template to create the chatbot [#create-chatbot-through-template]

1. Use the following template to create the chatbot.

    [Download the chatbot template](https://infobip-cdn-h0h7ekhqhgh4hgau.a02.azurefd.net/1g8x60m5haaeebc38sw9etdnqwq2orfxs6yjtxwklw767cqz71/Vocalize_chatbot_template.export)
2. [Import the template](https://www.infobip.com/docs/answers/create-chatbot/create-from-template#create-chatbot-from-template) into Answers.
3. Make the following changes:
    - Update the ```campaignId``` field with the ID that was generated in Postman.
    - [Make other changes](https://www.infobip.com/docs/answers/create-chatbot/create-from-template#create-chatbot-from-template-next-steps) as required. Example: Update the instructions or the image.

### Create the chatbot manually [#create-chatbot-manually]

Create the chatbot manually. In the chatbot, use the [API](https://www.infobip.com/docs/answers/chatbot-elements/core-elements#api) element to communicate with the Vocalize APIs.

For more information about creating chatbots and using chatbot elements, refer to the [Answers](https://www.infobip.com/docs/answers) documentation.

Do the following in the chatbot:

1. Get opt in from the end user to play the game.
2. If the end user opts in, get their details such as name, city, and email address.
3. Save this information in a Person profile in People. Use the [People profile](https://www.infobip.com/docs/answers/chatbot-elements/core-elements#people-profile) element.
4. Share the instructions of the game and the associated image with the end user. Ask the end user to send a recording of their response.
5. Save their response in a variable.
6. To send the end user's response to the Vocalize API, use the [API](https://www.infobip.com/docs/answers/chatbot-elements/core-elements#api) element to call the [Update score](https://www.infobip.com/docs/api/ai/vocalize/vocalize-submit-entry) endpoint. Configure the element as follows:
   1. Configure the **Request**.
      - **Path**: `https://api.infobip.com/vocalize/2/scores`
      - **Header**: Use the following Key-value pair:
        Key: `Authorization`  
        Value: `App`
      - **Body**: Use the following Key-value pairs:

            | Key | Value |
| --- | --- |
| campaignId | The ID that was generated in Postman |
| userId | ID of the end user. Example: {{endUserDestination}} |
| name | The name that you got from the end user. This name is used on the leaderboard. |
| audioUrl | The URL of the audio file received from the end user. |
| languageCode | en-US |

   2. In the **Response** tab > **Response body attributes** section, save the score calculated by the Visualize API to an attribute.  
      Use the following path:

      `$.score.final_score`
7. Share the final score with the end user.

## Privacy and data protection

Vocalize is designed with a focus on user privacy and data protection. The following guidelines apply to the storage and use of voice recordings submitted by end users:

- Voice recordings are used only to support the game experience and calculate results, such as scoring and leaderboard placement.
- Voice recordings are not used to train AI models or retained for future machine learning purposes.
- By default, voice recordings are temporarily stored to support campaign metrics and performance analysis.

    You can choose to have voice recordings automatically deleted immediately after processing, with no data retained.
- Voice recordings are never shared externally or used for any purpose beyond the scope of the campaign.