Set up your Server URL

Learn how to set up your server to receive and respond to messages from Vapi.

In the Account dashboard page, you can optionally specify a Server URL. This is your server’s URL that the assistant will use when sending status updates, performing function calls, and more.

Server Messages

All messages sent to your Server URL will be POST requests with the following body:

{
  "message": {
    "type": "function-call",
    "call": { Call Object },
    ...other message properties
  }
}

They include the type of message, the call object, and any other properties that are relevant to the message type. Below are the different types of messages that can be sent to your Server URL.

Function Calling

Vapi fully supports OpenAI’s function calling API, so you can have assistants ping your server to perform actions like sending emails, retrieve information, and more.

With each response, the assistant will automatically determine what functions to call based on the directions provided in the system message in messages. Here’s an example of what the assistant might look like:

{
  "name": "Ryan's Assistant",
  "model": {
    "provider": "openai",
    "model": "gpt-3.5-turbo",
    "functions": [
      {
        "name": "sendEmail",
        "description": "Used to send an email to a client.",
        "parameters": {
          "type": "object",
          "properties": {
            "color": { "type": "string" }
          }
        }
      }
    ]
  }
}

Once a function is triggered, the assistant will send a message to your Server URL with the following body:

{
  "message": {
    "type": "function-call",
    "call": { Call Object },
    "functionCall": {
      "name": "sendEmail",
      "parameters": "{ \"emailAddress\": \"[e-mail]\"}"
    }
  }
}

Your server should respond with a JSON object containing the function’s response, like so:

{ "result": "Your email has been sent." }

Or if it’s an object:

{
  "result": "{ \"message\": \"Your email has been sent.\", \"email\": \"[e-mail]\" }"
}

The result will be appended to the conversation, and the assistant will decide what to do with the response based on its system prompt.

If you don’t need to return a response, you can use the async: true parameter in your assitant’s function configuration. This will prevent the assistant from waiting for a response from your server.

Retrieving Assistants

For inbound phone calls, you may want to specify the assistant based on the caller’s phone number. If a PhoneNumber doesn’t have an assistantId, Vapi will attempt to retrieve the assistant from your server.

{
  "message": {
    "type": "assistant-request",
    "call": { Call Object },
  }
}

Your server should respond with a JSON object containing the assistant, like so:

{
  "assistant": {
    "firstMessage": "Hey Ryan, how are you?",
    "model": {
      "provider": "openai",
      "model": "gpt-3.5-turbo",
      "messages": [
        {
          "role": "system",
          "content": "You're Ryan's assistant..."
        }
      ]
    }
  }
}

If you’d like to play an error message instead, you can respond with:

{ "error": "Sorry, not enough credits on your account, please refill." }

Call Status Updates

During the call, the assistant will make multiple POST requests to the Server URL with the following body:

{
  "message": {
    "type": "status-update",
    "call": { Call Object },
    "status": "ended",
  }
}

Status Events

• in-progress: The call has started.
• forwarding: The call is about to be forwarded to forwardingPhoneNumber.
• ended: The call has ended.

End of Call Report

When a call ends, the assistant will make a POST request to the Server URL with the following body:

{
  "message": {
    "type": "end-of-call-report",
    "endedReason": "hangup",
    "call": { Call Object },
    "recordingUrl": "https://vapi-public.s3.amazonaws.com/recordings/1234.wav",
    "summary": "The user picked up the phone then asked about the weather...",
    "transcript": "AI: How can I help? User: What's the weather? ...",
    "messages":[
      {
        "role": "assistant",
        "message": "How can I help?",
      },
      {
        "role": "user",
        "message": "What's the weather?"
      },
      ...
    ]
  }
}

endedReason can be any of the options defined on the Call Object.

Hang Notifications

Whenever the assistant fails to respond for 5+ seconds, the assistant will make a POST requests to the Server URL with the following body:

{
  "message": {
    "type": "hang",
    "call": { Call Object },
  }
}

You can use this to display an error message to the user, or to send a notification to your team.