Getting Started with Voiceflow APIs

Key Takeaways

hi there I'm Alex a co-op at voice flow and today I'm going to be walking through using your first voice flow API by building a simple python interface to chat with your agent this video will be a follow along version of a getting started with apis guide that you can find in our voice flow docs it'll be primarily taught in Python but a lot of the lessons being explained here are applicable in multiple different languages in the written guides there's also examples in JavaScript with nodejs that you can use to follow along and all the code for this project in a finished form can be found on a GitHub in the description below you'll definitely also want to go there to check out the two voice flow project templates we'll need to follow along in this tutorial in this video you will learn how to get your voice flow project API key how to use a dialog manager API including how to send requests to the voice flow apis how to start a conversation how to parse the output traces you receive how to send user replies as well as how to deal with other kinds of traces like buttons end and other of things we'll also quickly cover some of the transcripts apis and examples more broadly on how you can learn how to use our other apis going through the case study of looking how to save our transcripts for our conversations okay let's get straight into it the first thing you need to do is make sure you've installed python on your operating system and then we want to create a new file called voiceflow API guide. py this will be the main file we're using for the entire guide and you can open it in whatever code editor you want here I'm using visual studio code so the first thing thing we'll do is import the requests Library it's what we'll be using to send API requests back and forth between our app and voice flow import requests next up we're going to be importing the templates to our voice flow account so in the documentation and in the description below there's a link to this GitHub repo where you can click on a link and get this voice flow API getting started part 1vf file in the top right corner simply click download raw file this will save it to your computer and then from inside the voice flow creator you can import it with this button in the top right so if I go here and then to my downloads I can import it in and boom here it is we can open it in the designer so this is a pretty basic project it's just a loop that's counting how many times and echoing back the user input but it's what I often use for testing these kinds of API integration so I recommend we follow along with it now the first thing we need to do is run the project so it's in the development mode if you just click run here and then answer one time how's it going it will just Echo back and now we've run it once and the next thing we need to do is publish the project so in the top right hand corner we can click publish no need to set a name for the publishing version and just click publish this will create a version that we can interact with through the API it's important to publish the agent like this because otherwise every single request we'll send we're just going to receive back an empty array and it's going to be really confusing to debug okay we already done that first part now on to part two let's see how we can get our voice flow API key what we need to do is from in here we can go to to the Integrations Tab and then API key and we can click copy API key and once we have the API key all we need to do is put it in so API key equals and then paste it in and boom that's step two done next up is the dialogue manager API this is the voice API we use to interact with the conversational part of our agent so having a discussion back and forth sending text messages getting answers back buttons images All That Jazz and the most important of those is the interact endpoint it's where we send our requests and get back an answer from voice flow so to that one we're going to write a function in Python So Def interact and it's going to take a user ID and a request that we're going to be sending to voice flow so user ID request now what we're going to add into this function is a blue line of code that we're going to use to actually send the request to voice flow I've just copied it from the docs here you can find it online but this is sending a post request to voice flow and the URL we're requesting is this dialog manager API we're specifying the user ID so which conversation we want to talk with and the interact endpoint in there we're going to include the request which is that payload we're sending to voice flow which will say either we're launching the conversation here's the text input the user gave or here's whatever action they did and then the last thing that's really important here is the authorization and the version ID the authorization is our API key so that's how we identify which conversation we're talking to and the version ID will actually specify which version we're using so here we're using a version Alias so not actually giving a full version ID we're just giving something that says eduction so that's the one when we click publish online it sort of stores a snapshot of our agent so that if we want to make any changes those aren instantly reflected in our deployed version to push them to production we've got to click publish and then after this just to see if it's working we will print the response so print response. Json and this just prints the response that our voice API will send back so just to run one test we're going to set up some really basic code we're going to get the user's name and use that as their user ID and then we're going to send a launch request so to get the user ID you have to just do name equals input and then we're going to write what's your name and then to send the request we're going to use interact that function we just wrote and we're going to pass in the name as a user ID and as a payload we're going to put type as launch so this just tells vo slow hey we want to start a new conversation and now we should be ready to run our program so then if we just pull up our terminal and run Python 3 voice API guide. it will ask us our name so I tell my name is Alex and here we saw it Center request to voice flow replied hi there Python and we can actually see that this replicates exactly what's inside our voice FL project so if we go here it says hi there python let's say we want to update it so hi there python 2 and we put two explanation marks and then we click publish so now having published this version if we run the script again uh test we'll see the answer has our new reflected update so boom we have our first connection for voice API so obviously when you're having a discussion with somebody you're not answering ing back and forth in big piles of Json and code like we have here we want to be able to get back those messages that voice flow is outputting that's because here thees from the dialog manager API are returning in what's called an array of traces traces is just voice flows concept everything that your agent can output and then we need to parse these outputs to be able to display them properly so that could be as simple as just rendering the text that we get back but as complicated as showing images carousels buttons and all that jazz so to deal with these traces and get a better output instead of just printing the output Json we're actually going to do a for Loop so for Trace in response. Json will iterate over every single one of the traces in this array here there's two where it says hi there Python and then echoing so for each of these traces we're going to check if the trace is a message Trace so if Trace if the type of the trace is a text message then we're just going to print its output and as we can see here um if we look at the traces we have type equals text and then the message is stored in here in a variable called message so so we're going to do print Trace it's payload which is the actual contents and then message and now after you run this new code mangoes boom we can actually see the output from our conversation so wow we have our first like working readable output now this isn't so much of a conversation as I'm asking voice something and it's giving me one answer back so let's figure out how we can can have a conversation going back and forth so to have a conversation going back and forth we're just going to make a loop that runs forever and just gets an input from the user and sends an answer to voice flow and goes back and forth printing the output so all we're going to do for this is a loop while true which means it's never going to stop running we going to get user input so next input equals input and then say something we'll put a back sln on these so that it prints nicer and then we're going to pass that input to voice flow with request so we're going to say interact again the same user ID so that we have the same conversation and then we're going to send a different type of request above we sent a launch request because we were starting the conversation a new we don't want to be starting the conversation over each time we send an interaction so now we're going to send a text payload so that's going to be type is text and then for text interactions we're going to set that type equals to text and then we're going to pass a payload so the payload is actually going to be the user's message so next input is the answer and then if we just run this again you be able to see my name is Alex one okay how's it going and we can see voiceful answering here Echo one how's it going blah blah blah it's answering it back and boom we're able to have a conversation back and forth with our voice flow agent just for fun let's try adding some AI in here and I'll show you how fast it is in voice flow so we can go here AI step response Ai and then we can just get the AI to respond so um tell a funny joke based on last utterance you just publish this new version and the new version is successfully published and if we just stop our script and start it again make sure when you're testing between different versions you want to use different user IDs so let's just let's just put in some random numbers um I love mangoes and we can see how easy it is to get interactions with large language models like chat GPT through voice flow and we can see how little code was required here to interact with the voice flow apis okay now we're going to deal with a slightly more complex voice flow agent other than just a loop that Echoes back exactly what I said so for this we're going to need to download a new template it's in the description below and in the documentation here if you click import second project example we can download it again top right and then from voice flow just leave your project go back to your dashboard import import this part two file and boom it should be added and now you can open it up inside voice flow again we have to do the same process to run it and publish it so let's just go in here um I like pink and then it's run once we should be good now and we can just click publish in the top right publishing a new version to the public web and then now we're going to get our API key so that we can interact with it so again interactions copy API key and then let's go back to our python script and paste it in so we save our file and now we can run some new code um blah blah and then boom it's asking us our new favorite color so we have the second example loaded but let's have a quick conversation with it favorite color is let's say orange would you prefer an orange hat or an orange T-shirt let's say a t-shirt didn't work that's because it actually didn't even show me the buttons if you look at the voice flow example here in the workflow it's actually supposed to serve me some options for hat shirt but here because those buttons weren't displayed I just went down the no match trace and then just endered the conversation early so let's figure out how we can display those buttons so the issue here is that the buttons were never actually displayed in my text console here and we never knew that they even came because there was nothing printed in our python terminal what we'll actually do now is add a quick else condition that is often useful when you're writing these kinds of custom interfaces to know which traces your program is not dealing with so here we're just for now dealing with text traces so let's see what else is coming through so we're going to do here is add an else condition to see all the traces that we're not handling other than text so if you do else print unhandled trace and then we're just going to put the uh Trace we're just going to paste it in and now if we stop the code and run it again uh blah blah orange we can actually see there's an unhandled Trace here for a path switch don't need to worry about that that's just vo telling us which direction we're going but there's also an unhandled trace of type choice and in here we can actually see the options for our buttons so hat shirt neither so that's what we're going to want to render so now that we know it's here let's add some code to actually handle the buttons so the way buttons are dealt with is that whenever you click the button you have to send back a certain answer that vo expects so here we can see this action in here under request and then it says type equals path and this random string so what we're going to do is whenever we receive buttons we're going to store them and then send them back to voice Lo so the first thing we're going to do is make an array of all the buttons that our code currently has so buttons equals an empty array then we're going to deal with if we have a Trace so L if so this is other condition Trace type is choice so choice is the name of the button Trace it's a little bit complicated but you can find this all in the voice docs we're going to set the buttons to the actual payload so equals Trace payload oops buttons and then we're going to print the options we get to choose from so print choose one one of the following and then we're going to print each of these options and then use them later to actually figure out what button the user wants to click obviously here there's no button interface in Python if we had a DUI we could do that but we're just going to present a list of options so choose one of the following and then we're going to print all the options so for I in range L buttons this is just looping through all the buttons and printing their index so print and then we're going to do FST string which is just a way of formatting text and then i+ plus one so that we start at 1 2 3 4 5 and we're going to put the buttons name so buttons this is the I button so as we it way through the list and then the name this is maybe a little bit of complicated code for new beginner programmers but this is basic python to Loop through an array and then print the index and take an item from the array and print its name here so once we did it we can save our code actually made a little mistake in here this should be single quotes because otherwise it's going to break the interpretation of the string but if we just save it and run the code again and we type uh test mango it's now presenting the three options for the buttons just like in the actual voice F agent but now if I want to actually input the one so let's say I say uh one it's just not going to know that I wanted to do the hat and it's just going to again go down this no match path so we need a way to understand if we have buttons to actually send those requests instead of interpreting our answer from our user as basic text so we're actually going to deal with a case where there's buttons or no buttons differently so if there are buttons so length of the array of buttons is more than zero then we're going to deal with the buttons and otherwise we're going to deal with it just as normal text so now we're going to have some input code to get the actual selection from the user so button selection equals input and then we're going to say choose a button number or just send a reply and we're going to get their user input and we're going to store that in a variable called button selection and then here we're going to have a try catch so that's just we're going to try to see if it's a correct number then we'll send it if it isn't then we'll just interpret it as normal text imagine they said like instead of answering like one of the button selections they just gave an input that's like oh I want whatever we actually do this time want to go down this no match path correctly so we're going to try to see if it fits in so we're going to do interact again with the same user ID so it's the same conversation thread name and now we're going to send a different kind of payload instead of actually sending a text or a launch request we're just going to send the answer that the button is telling us to so we're going to go to buttons we're going to take the integer number of the button selection so that's just converting the string of like if they type letter one it'll convert into the number one and then because we're zero index in programming we're going to subtract one so we going to take the button that they chose and then it'll send its request so that is just request so in case something goes wrong imagine it's not convertiable we're just going to put an exception and then we're going to interact like it's normal text so interact name we can actually just copy off the code from down here and by instead of next user input we're going to do button selection what I actually forgot to do up here is set the buttons to Global this is just a python thing where if you're updating variables from inside a function um you need it to be Global externally but if we run it again it should work now alex9 purple and boom now we have our three options showed up and we see this custom text for choose a button number so let's say we want a shirt we put in two click enter and wow I think it worked it says okay let's get a purple shirt here's an example and it went down this correct path right here this is an orange obviously but we also see a different type of Trace visual turns out that this visual Trace is actually the image here we see the image and then we have the link to the actual image itself online so I haven't implemented this in this code right here but as a challenge I encourage you guys to try and make a way of rendering the visual payloads from voice flow in Python so you could use things like some image libraries or map plot lib but give it a try and make sure to comment in the video description below if you got that challenge done okay so it's super that we got the buttons working now but I also see one last Trace that says end this is a bit weird imagine I want to give a reply to my voice agent here and said like can I get the shirt it's actually just starting the conversation over again that's because when a voiceful conversation ends it sort of stops it and then if you send another request as if you trying to continue it it'll just imagine that was a launch request and then start from the start so here we see what's your favorite color it's actually just forgetting that we passed here and it's going straight back to start that's because we hit this end and we actually need our code to deal off the fact that the conversation ended so we're going to add one last system which is keeping track of whether the conversation is alive or dead so to get whether the conversation is alive or dead if the interaction ends normally we're just going to return true a Boolean but if we hit a trace that says end so LF Trace type equals end now if we have a trace of ends we're just going to return false saying the conversation is no longer alive and then we're going to store a variable is alive equal to this interact payload and then we're only going to Loop while it's alive so while is alive and then here we're going again update is alive and we're going to update is alive and just last one here save this code if we run it again Alex this number um blue I can choose a hat and then boom the conversation actually ended in the python code escaped so we can just put one last little print saying print conversation ended and boom now we have a fully fledged python script to discuss with a voice FL agent through the dialogue manager API great job the last part of this guide is going to focus on how you can learn how to use voice flow's other apis and here we're going to go with the example of the transcripts AP the lessons here will be applicable to every API we have to offer so we're going to walk through how to use the docs how to experiment how to get the info we know and then how to actually implement the code here in Python so one maybe unintuitive thing about some of the stuff on voice flow is that whenever we have a conversation there is this transcripts tab in here in our agent but right now it's empty even though we just had a bunch of conversations with it through our python terminal that's because transcripts have to be saved through the transcripts API so let's figure out how you would do that so so if we go here to the API reference and then we go to the transcripts endpoint is down here um we can actually look there's a bunch of endpoints for transcripts and we want to be creating a transcript so it looks like we should go to this endpoint here we have our documentation and the way you should look at this is I like reading this description real quick and then switching it over to a code I'm familiar with so here it's python that's code in a bunch of different languages but here we're doing Python tutorial so here we see we have to send it to api. voice.com transcripts and then this documentation can actually be populated with some information so let's just say project ID version ID session ID so we see that here we have a payload we need to send along with it in the request so we'll need to get our project ID version ID and session ID and then we'll be able to send this request so let's first of all try out doing it from just inside the docs here he are sending actual requests to our actual voice flow project so first of all let's get our API key so if we go to Integrations we can copy our API key here paste it in next we're going to need our project ID and our version ID this is useful to specify what's going on so if you go to settings scroll down there's project ID let's copy it and then let's get our version ID super this version ID doesn't actually update every single time you publish so it shouldn't be an issue but if you are having issues try making sure it's up to date and then your session ID is actually just the user ID like it describes here so our user ID let's find one from a past conversation um last conversation I called myself Alex 98123 so let's place this in and then if we click try it it actually run the request on a real voice API we see it succeeded so it save the session ID for Alex 98123 and if you go back and look at our project and then go to the transcripts tab boom we can see that we saved our transcript so here's the conversation we had blue hat and that's actually exactly what I did here blue and then I chose button one which is hat so we see great success now we have to do is implement the code that's from the docs here and put it into our python project or for example if you're doing a node you would do this code or just for General use case you can see the basic curl request that we' be sending so now we know how to do it let's implement it in Python so the first thing we'll need to do is we need to create variables for our project ID and version IDs so if we go to the top here and we make new variables project ID make sure to store them as strings version version ID and make sure store this one too amazing okay next up we're going to have to actually create a function that we can use to save the transcripts so instead of it's different to interact so let's write a new function def save transcript and then we're just going all we need is a user ID to identify which transcript we're going to save so user ID and then if we actually go to this code here and copy paste it we can paste it into our python now we have the URL we need and all we need to do is make sure we're taking in the right information so instead of this hardcoded project ID we're going to do project ID I'm going to do version ID here and then we're going to take the user ID we just got in so user ID and then we also have to update the API key so API key updated now it will do the put request it will send the response and then um let's just check that it worked so if response. okay which is a variable that let us know that like it worked well um whoops no need for curly braces we're just going to print saved transcript okay and last thing we need to do is actually to run the save transcript function if you try to save the same transcript twice it'll just update it so all we need to do is add this every time we send an interaction from the user so let's say um user sent their input we're just going to save the transcript here now if we run our code um mango boy uh let's say [Music] orange H our missing user ID that's because here we forgot to put the name my bad let's run it again angle Boy 2 uh let's say yellow and it saved the transcript we see printed it so let's just check the transcripts tab right now we refresh we see mango Boy 2 said yellow and then it gave the answer and then let's say I want a shirt it sent it it save the transcript again and it entered the conversation and now if we reload from here inside voice flow we can see the updated version of the transcript and then we can see that the conversation has finished here this is super useful if you want in later to study the conversations that happened and Mark is red mark safe for later but also more generally we just learned how we can do the process of adding a new API from voice flow using this interactive documentation testing it out in here and then copy pasting the code into our own function and then adapting it so here we need to change some variables but sometimes you you might need to change a couple other things but this lesson should really be helpful to you if you're looking to do other things like adding documents to your knowledge base getting analytics doing testing or anything like that so congratulations you just finished the getting started with voice flow apis guide hopefully you've gotten a good idea of how you can use voice fls apis to build custom interfaces or interact of your projects programmatically I strongly encourage you to use your new found skills to look at our demos and examples repository that's full of a bunch of projects built on these voice FL apis that you can really use to inspire yourself and then once you've looked at them make your own creative custom interfaces and then again post them in the comments or join our voice flow community on Discord and share them there we really love to see what people are building a voice flow if you're looking for even more resources you can look at our YouTube that has a bunch of videos and guides and tutorials and discussions about building these kinds of custom interfaces around voice flow and of course I encourage you to take a good look around the new voice blow documentation that will really teach you everything you need to to know from actually building the agent itself so things like entities intents how to use llm blocks but also some research best practices how to deploy and here you can use your new found skills to build creative custom interfaces with the apis so go out there and build something great and I'll see you around