VOGO Voice – Knowledge Base

CARTO inserting input data

Estimated reading time: 5 min

CARTO, an open source tool built on PostGIS and PostgreSQL, is a scalable solution especially for spatial analytics. CARTO’S capabilities are often leveraged to overcome the limitations of visualization tools, handle large datasets, multiple layers and advanced spatial data. 

This instructional tutorial aims at illustrating a use-case on how to make use of a CARTO dataset to insert input data. Adopting a comprehensive methodology, the tutorial is dedicated towards presenting a guided step-by-step walk-through to understand how to configure a CARTO instance within a custom interaction model and design it to capture the end-user’s input and relay tailor-made, purposeful voice responses by addressing the user’s specific requirements.


  •  VOGO Voice account: https://www.vogovoice.com/
  • Access rights to the Intents section under Settings.
  • Access rights to the Interaction builder platform.
  • CARTO Account username and API key.
  • Knowledge in writing SQL queries.

Setting up a CARTO connector instance

In order to create a CARTO connector instance
1. Log into your VOGO Voice account to be directed to VOGO Voice Management Console (https://account.vogovoice.com)
2. Navigate to Settings on the top right-hand corner of the Dashboard and select Integration from the list of tabs displayed.
Settings > Integration
3. Click on the Add Button on the top left-hand corner of the screen.

4. In the Select Account Type window, choose the CARTO icon from the list of connectors and click Create Connector button which opens up Add New CARTO Account window.
5. Populate the required fields in the Add CARTO Connector window.

Field values

  • Assign a Name to the instance of the connector created. Here, the given name is MyNotes
  • Provide the Username and API key of the CARTO account to which access is required.

The additional parameters in the Add CARTO Connection window are optional fields that need to be populated depending on the requirements of the skill. 

To learn more about the additional parameters and how to generate an API key refer the CARTO connector guide: https://university.vogovoice.com/kb/carto/

6. After filling in the required fields click the Save button to set up and integrate the connector instance with the platform.

Create a custom intent

Create an appropriate intent to be invoked for executing an interaction flow mapped to it, the purpose here being to add a new item and update the existing list of items on the user’s to do list.

Create an intent titled ‘My Notes’ with a set of suitable sample utterances mapped to it. Let’s say the sample utterances are: “Add {item} to my notes” and “I would like to add {item} to my notes”, where ‘item’ is the slot name. Assign the slot type to ENVIRONMENT_Any which is a global slot with predefined values.

To learn how to create custom intents refer the guide: https://university.vogovoice.com/kb/creating-intents/

Steps to Configure the CARTO connector instance 

Once the CARTO connector has been created navigate to Interactions and click on the Interactions button at the bottom right-hand corner of the screen. Select the ‘My Notes’ intent to be directed into the Interaction builder platform.

Now let’s create an interaction flow to return a resultset of data in the form of a curated voice response by capturing the specific input of the user that needs to be added to his existing list of items.

  1. In the flow diagram area, you will be able to see the Start and Response component
  2. Unlink the Start component from the Response card by clicking the delete icon placed in the middle of the chain.

3. Drag and drop a CARTO component onto the flow diagram area and connect the anchor symbol of Next on the Start component to the CARTO connector.

🖍 Note: To interconnect the different components click on their respective Anchor symbols so as to chain and hold them in the interaction flow.

4. Double click the CARTO component, or click the pencil to access the Configuration window and fill in the required fields to insert the user specific input data.

Setting up the configuration fields for c1

Name: The name is provided by default and can be changed manually. It is used to identify the connector instance and how it is referenced throughout the flow. 

Query: PostgreSQL INSERT statement syntax is the query language made use of to interact with a CARTO database. Here, the query is framed to capture and insert the user specific input data.
INSERT INTO my_notes (notes, user_id) VALUES
 ('{{inputs.item.value}}', '{{session.userId}}')

5. Drag and drop another CARTO component onto the flow diagram area and connect the anchor symbol of Next on the preceding CARTO component to it.

6. Double click the CARTO component, or click the pencil to access the Configuration window and fill in the required fields.

Setting up the configuration fields for c2

Name: The name is provided by default and can be changed manually. It is used to identify the connector instance and how it is referenced throughout the flow. 

🖍 Note: Ensure not to provide the same name for both the connector instances.

Query: Frame the query to serve the purpose of selecting and displaying the newly inserted input data along with the existing list of items in the user’s to do list such that it produces the desired result of displaying the updated list of items.
SELECT * FROM my_notes 
where user_id = '{{session.userId}}'

7. Drag and drop a Response component onto the flow canvas. You can alternatively right-click on the anchor icon and choose the response component.
8. Connect the second CARTO component to the Response card.
9. Click on the Voice icon of the Response card to open up the Speak pop-up window and type the voice action intended to be spoken to the user upon capturing the input data provided by the user.
  Say: {{inputs.item.value}} is added to the list. 
  Your current notes are {{# showList 
connectors.c2}} {{notes}} {{/showList}}

To learn about different template engines to be followed to run functions visit https://university.vogovoice.com/kb/template-engine/

To add a display message in a display voice-assisted device
1. Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
2. Populate the required fields and click the Save button. 
Title: My Notes
Display Message:  {{# showList connectors.c2}} {{notes}}   

For further reference on how to populate the additional fields visit https://university.vogovoice.com/kb/guide-response-component/

The screenshot below captures the aforementioned interaction flow

Testing and Validation

  1. Click on the Test button next to the Flow Editor button on the interaction builder platform. 

2. In the Tests pop-up window that appears click the + button on its top right-hand corner. 

3. Fill the Name field of the Test Response window that shows up.
4. In the Conversation section of the Test Response, My Notes intent through which this interaction flow has been initiated will be auto-generated in the User invokes field.
1. Fill the ‘With slots’ field titled ‘item’ under Conversation with the user’s input  ‘respond to urgent emails’ to be added to the existing list of items.

5. Finally, click the Save button to save the input and perform the test.
6. To validate the Test Response, click on the lightning symbol on the left-hand side of the test case. 

7. On the resulting Test Response window, the blue chat bubble presents the input message within the Response component. The 2 lightning bolt symbols in yellow represent the CARTO connector instances.

8. Click on the chat bubble to see the details of the response.

9. To take a detailed look at the data fetching part of the connector instance, click on the respective lightning bolt icon highlighted in yellow. 

To know more about testing an interaction refer https://university.vogovoice.com/kb/testings/

Congratulations! You have successfully created a custom interaction model by making use of a CARTO database that allows the provision of inserting an end-user’s input  data in order to maximize the user’s experience of the functionality of the custom skill.

👍 Note: To test the functioning of the interactions on your device you have to deploy the custom skill to facilitate the skill with the new edits. To accomplish this, click on the Deploy button seen at the bottom of the Skill Settings pop-up window.

To know how to deploy a custom skill visit https://university.vogovoice.com/kb/deploying-a-skill/

Was this article helpful?
Dislike 0
Previous: CARTO: Near Me
Next: Learn More