bephrem/developing-locally (#66)

* image

* the problem

* Update developing-locally.mdx

* save

Author: bephrem1

mint.json

@@ -137,7 +137,12 @@
         },
         {
           "group": "Server URL",
-          "pages": ["server-url", "server-url/setting-server-urls", "server-url/events"]
+          "pages": [
+            "server-url",
+            "server-url/setting-server-urls",
+            "server-url/events",
+            "server-url/developing-locally"
+          ]
         },
         {
           "group": "Phone Calling",

server-url.mdx

@@ -43,6 +43,14 @@ To get started using server URLs, read our guides:
   <Card title="Events" icon="bell-on" iconType="solid" href="/server-url/events">
     Read about the different types of events Vapi can send to your server.
   </Card>
+  <Card
+    title="Developing Locally"
+    icon="laptop-arrow-down"
+    iconType="solid"
+    href="/server-url/developing-locally"
+  >
+    Learn about receiving server events in your local development environment.
+  </Card>
 </CardGroup>
 
 ## FAQ
@@ -55,8 +63,8 @@ To get started using server URLs, read our guides:
     - **Workflow Orchestrator:** platforms like [Pipedream](https://pipedream.com) & [Make](https://www.make.com) allow you to program workflows (often without code) that can receive events via HTTP triggers.
 
     The main idea is that Vapi needs a location on the Internet that it can drop data to & converse with your application.
-    </Accordion>
 
+  </Accordion>
   <Accordion title="Why not just call them webhooks?">
     [Webhooks](/glossary#webhook) are traditionally unidirectional & stateless, with the target endpoint usually only replying with a status code to acknowledge message reception. Certain server URL events (like assistant requests) may require a meaningful reply from your server.
 

server-url/developing-locally.mdx

@@ -1,5 +1,88 @@
 ---
 title: "Developing Locally"
 sidebarTitle: "Developing Locally"
-description: "lorem."
+description: "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.
+
+<Info>
+  `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.
+</Info>
+
+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](https://ngrok.com/) to create a secure tunnel to our local machine. The flow will look like the following:
+
+<Steps>
+  <Step title="Start Our API Locally">
+    We will start our server locally so it is listening for http traffic.
+  </Step>
+  <Step title="Start Ngrok Agent">
+    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.
+  </Step>
+  <Step title="Copy Public Ngrok URL">
+    Ngrok will give us a public URL that can receive traffic. We will use this as a server URL
+    during development.
+  </Step>
+  <Step title="Trigger Call Events">
+    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.
+
+  </Step>
+</Steps>
+
+#### 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:
+
+<Steps>
+  <Step title="Install Ngrok Agent CLI">
+    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.
+  </Step>
+  <Step title="Start Ngrok Agent">
+    Run the command `ngrok http 8080`, this will create the tunnel with Ngrok's servers.
+    <Note>Replace `8080` with the port your server is running on.</Note>
+  </Step>
+</Steps>
+
+#### Copy Public Ngrok URL
+
+You will see an output from the Ngrok Agent CLI that looks like the following:
+
+<Frame caption="Terminal after running the 'ngrok' command forwarding to localhost:8080 — the 'Forwarding' URL is what we want.">
+  <img src="/static/images/server-url/developing-locally/ngrok-cli-ui.png" />
+</Frame>
+
+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](/server-url/setting-server-urls) in Vapi.
+
+<Note>
+  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).
+</Note>
+
+#### Trigger Call Events
+
+We will now be able to see call events come through and get logged to our terminal.
+
+Feel free to follow any of our [quickstart](/quickstart) guides to get started with building assistants & conducting calls.

server-url/setting-server-urls.mdx

@@ -96,4 +96,4 @@ Events are only sent/assigned to 1 server URL in the priority stack. Here's the
 3. **Phone Number:** if a phone number has a server URL, it will be used over the account-wide URL
 4. **Account-wide:** Default / "lowest" importance. It will be used if no other server URL is set.
 
-You will most commonly set a server URL on your account & on specific assistants.
+You will most commonly set a server URL on your account, and/or on specific assistants.