Skip to content

Latest commit

 

History

History
105 lines (75 loc) · 4.61 KB

developing-locally.mdx

File metadata and controls

105 lines (75 loc) · 4.61 KB
title sidebarTitle description
Developing Locally
Developing Locally
Learn how to receive server events in your local development environment.

The Problem

When Vapi dispatches events to a server, it must be able to reach the server via the open Internet.

If your API is already live in production, it will be accessible via a publicly known URL. But, during development, your server will often be running locally on your machine.

`localhost` is an alias for the IP address `127.0.0.1`. This address is called the "loopback" address and forwards the network request within the machine itself.

To receive server events locally, we will need a public address on the Internet that can receive traffic and forward it to our local machine.

Tunneling Traffic

We will be using a service called ngrok to create a secure tunnel to our local machine. The flow will look like the following:

We will start our server locally so it is listening for http traffic. We will take note of the port our server is running on. We will use the `ngrok` command to start the [ngrok agent](https://ngrok.com/docs/agent) on our machine. This will establish a connection from your local machine to ngrok's servers. Ngrok will give us a public forwarding URL that can receive traffic. We will use this as a server URL during development. We will conduct normal calls on Vapi to trigger events. These events will go to the Ngrok URL & get tunnelled to our local machine. 
We will see the event payloads come through locally & log them in our terminal.

Starting Our API Locally

First, ensure that your API is running locally. This could be a Node.js server, a Python server, or any other server that can receive HTTP requests.

Take note of the port that your server is running on. For example, if your server is running on port 8080, you should be able to access it at http://localhost:8080 in your browser.

Starting Ngrok Agent

Next we will install & run Ngrok agent to establish the forwarding pathway for Internet traffic:

Install the Ngrok agent by following Ngrok's [quickstart guide](https://ngrok.com/docs/getting-started). Once complete, we will have the `ngrok` command available in our terminal. Run the command `ngrok http 8080`, this will create the tunnel with Ngrok's servers. Replace `8080` with the port your server is running on.

Copy Ngrok Forwarding URL

You will see an output from the Ngrok Agent CLI that looks like the following:

Copy this public URL that Ngrok provides. This URL will be accessible from the open Internet and will forward traffic to your local machine.

You can now use this as a server URL in the various places you can set server URLs in Vapi.

This URL will change every time that you run the `ngrok` command. If you'd like this URL to be the same every Ngrok session, look into [static domains on Ngrok](https://ngrok.com/docs/getting-started#step-4-always-use-the-same-domain).

Trigger Call Events

We will now be able to see call events come through as POST requests, & can log payloads to our terminal.

Feel free to follow any of our quickstart guides to get started with building assistants & conducting calls.

Troubleshooting

Here's a list of a few things to recheck if you face issues seeing payloads:

  • Ensure that your local server is running on the port you expect
  • Ensure that you input the correct port to the ngrok http {your_port} command
  • Ensure your route handling server URL events is a POST endpoint
  • Ensure your path on top of the base forwarding url is set correctly (ex: /callbacks/vapi)