Applications

The Vapi4k Ktor plugin allows you to define three types of applications:

InboundCall
OutboundCall
Web

InboundCall Applications

InboundCall applications handle requests from the Vapi platform resulting from calls to Vapi. Responses are specified using the inboundCallApplication{} function.

InboundCall Application Ktor Config

  fun Application.module() {
    install(Vapi4k) {
      inboundCallApplication {
        serverPath = "/inboundApp"
        serverSecret = "12345"

        onAssistantRequest { requestContext: RequestContext ->
          // Describe the assistant or squad
          assistant {
            firstMessage = "Hello! How can I help you today?"

            openAIModel {
              modelType = OpenAIModelType.GPT_4_TURBO
              systemMessage = "You're a polite AI assistant named Vapi who is fun to talk with."
            }

            deepgramVoice {
              voiceIdType = DeepGramVoiceIdType.LUNA
            }
          }
        }

        // Log the ASSISTANT_REQUEST, FUNCTION_CALL, and TOOL_CALL requests
        onRequest(ASSISTANT_REQUEST, FUNCTION_CALL, TOOL_CALL) { requestContext: RequestContext ->
          logger.info { requestContext }
        }
      }
    }
  }

OutboundCall Applications

OutboundCall applications are used to make outgoing calls from the Vapi platform. Responses are specified using the outboundCallApplication{} function.

OutboundCall Application Ktor Config

  fun Application.module() {
    install(Vapi4k) {
      outboundCallApplication {
        serverPath = "/callCustomer"
        serverSecret = "12345"

        onAssistantRequest { args ->
          assistant {
            firstMessage = "Hello! I am calling to ask you a question."

            anthropicModel {
              modelType = AnthropicModelType.CLAUDE_3_HAIKU
              systemMessage = "You're a polite AI assistant named Vapi who is fun to talk with."
            }

            elevenLabsVoice {
              voiceIdType = ElevenLabsVoiceIdType.PAULA
              modelType = ElevenLabsVoiceModelType.ELEVEN_TURBO_V2
            }
          }
        }
      }
    }
  }

OutboundCall Client

fun outboundCallExample() {
  val response =
    vapiApi()
      .phone {
        outboundCall {
          serverPath = "/callCustomer"
          phoneNumber = "+14155551212"
        }
      }

  runBlocking {
    println("Call status: ${response.status}")
    println("Call response: ${response.bodyAsText().toJsonElement()}")
  }
}

Web Applications

Web applications are used to create web page-based conversations. Responses are specified using the webCallApplication{} function.

Web Application Ktor Config

  fun Application.module() {
    install(Vapi4k) {
      webApplication {
        serverPath = "/talkApp"

        onAssistantRequest { requestContext: RequestContext ->
          assistant {
            firstMessage = "Hello! How can I help you today?"

            groqModel {
              modelType = GroqModelType.LLAMA3_70B
              systemMessage = "You're a polite AI assistant named Vapi who is fun to talk with."
            }

            playHTVoice {
              voiceIdType = PlayHTVoiceIdType.JACK
            }
          }
        }

        // Describe the button configuration
        buttonConfig { requestContext: RequestContext ->
          position = ButtonPosition.TOP
          offset = "40px"
          width = "50px"
          height = "50px"

          idle {
            color = ButtonColor(93, 254, 202)
            type = ButtonType.PILL
            title = "Have a quick question?"
            subtitle = "Talk with our AI assistant"
            icon = "https://unpkg.com/lucide-static@0.321.0/icons/phone.svg"
          }

          loading {
            color = ButtonColor(93, 124, 202)
            type = ButtonType.PILL
            title = "Connecting..."
            subtitle = "Please wait"
            icon = "https://unpkg.com/lucide-static@0.321.0/icons/loader-2.svg"
          }

          active {
            color = ButtonColor(255, 0, 0)
            type = ButtonType.PILL
            title = "Call is in progress..."
            subtitle = "End the call."
            icon = "https://unpkg.com/lucide-static@0.321.0/icons/phone-off.svg"
          }
        }
      }

      // Create a route for the talk page
      routing {
        get("/talk") {
          call.respondHtml {
            head {
              title { +"Talk Button Demo" }
            }
            body {
              h1 { +"Talk Button Demo" }
              vapiTalkButton {
                serverPath = "/webApp"
              }
            }
          }
        }
      }
    }
  }

Web Application HTML Page

  fun Application.talkPage() {
    routing {
      get("/talk") {
        call.respondHtml {
          head {
            title { +"Talk Button Demo" }
          }
          body {
            h1 { +"Talk Button Demo" }
            vapiTalkButton {
              serverPath = "/talkApp"
              // post args are optional
              postArgs = mapOf(
                "arg1" to "10",
                "arg2" to "20",
                "name" to "Jane",
              ).toJsonElement()
            }
          }
        }
      }
    }
  }

Application Properties

A Vapi4k configuration can include multiple application declarations. The default serverPath value is /vapi4k. If there is more than one application of a given type, you will need to specify a unique serverPath property value for each application.

The serverSecret property is optional.

Application Functions

All applications require a call to onAssistantRequest{}. Its lambda will define the desired assistant, assistantId, squad, or squadId for the request.

All applications allow you to define callbacks for requests and responses using the onAllRequest{}, onRequest{}, onAllResponse{}, and onResponse{} functions. The arguments for onRequest{} and onResponse{} are of type ServerRequestType.

These functions are also available globally in the Vapi4kConfig context.

All applications can optionally call onTransferDestinationRequest{} to define a transfer destination.

AssistantRequestUtils provides useful utility functions for working with assistant requests.

When writing applications, you are likely to reference the RequestContext object. It contains all the request data. The raw JSON request is available in the request property and can be accessed with the JSONElement utilities described here.

Last modified: 04 October 2024