Chat

Chat quickstart

Build your first text-based conversation with a Vapi assistant in 5 minutes

Overview

Build a customer service chat bot that can handle text-based conversations through your application. Perfect for adding AI chat to websites, mobile apps, or messaging platforms.

What You’ll Build:

  • A working chat integration that responds to user messages
  • Context-aware conversations that remember previous messages
  • Both one-shot and multi-turn conversation patterns

Agent Capabilities:

  • Instant text responses without voice processing
  • Maintains conversation context across multiple messages
  • Compatible with existing OpenAI workflows

Prerequisites

  • A Vapi account
  • An existing assistant or willingness to create one
  • Basic knowledge of making API requests

Scenario

We’ll create a customer support chat for “TechFlow”, a software company that wants to handle common questions via text chat before escalating to human agents.

1. Get Your API Credentials

1

Open the Vapi Dashboard

Go to dashboard.vapi.ai and log in to your account.

3

Copy your API key

Copy your Private API Key. You’ll need this for all chat requests.

Keep this key secure - never expose it in client-side code.

2. Create or Select an Assistant

2

Create a new assistant (or use existing)

  • Click Create Assistant if you need a new one
  • Select Blank Template as your starting point
  • Name it TechFlow Support
  • Set the first message to: Hello! I'm here to help with TechFlow questions. What can I assist you with today?
3

Configure the system prompt

Update the system prompt to:

System Prompt
You are a helpful customer support agent for TechFlow, a software company. 
Your role:
- Answer common questions about our products
- Help troubleshoot basic issues  
- Escalate complex problems to human agents
Keep responses concise and helpful. Always maintain a friendly, professional tone.
4

Copy the Assistant ID

After publishing, copy the Assistant ID from the URL or assistant details. You’ll need this for API calls.

3. Send Your First Chat Message

1

Test with curl

Replace YOUR_API_KEY and your-assistant-id with your actual values:

First Chat Request
$curl -X POST https://api.vapi.ai/chat \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "assistantId": "your-assistant-id",
>    "input": "Hi, I need help with my TechFlow account"
>  }'
2

Verify the response

You should receive a JSON response like:

Chat Response
1{
2  "id": "chat_abc123",
3  "assistantId": "your-assistant-id",
4  "messages": [
5    {
6      "role": "user",
7      "content": "Hi, I need help with my TechFlow account"
8    }
9  ],
10  "output": [
11    {
12      "role": "assistant",
13      "content": "I'd be happy to help with your TechFlow account! What specific issue are you experiencing?"
14    }
15  ],
16  "createdAt": "2024-01-15T09:30:00Z",
17  "updatedAt": "2024-01-15T09:30:00Z"
18}

4. Build a Multi-Turn Conversation

1

Continue the conversation

Use the previousChatId from the first response to maintain context:

Follow-up Message
$curl -X POST https://api.vapi.ai/chat \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "assistantId": "your-assistant-id",
>    "previousChatId": "chat_abc123",
>    "input": "I forgot my password and can't log in"
>  }'
2

Test context awareness

Send another message to verify the assistant remembers the conversation:

Context Test
$curl -X POST https://api.vapi.ai/chat \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "assistantId": "your-assistant-id", 
>    "previousChatId": "chat_abc123",
>    "input": "What was my original question?"
>  }'

5. Pass Dynamic Variables

1

Configure variables in your assistant

In your assistant’s system prompt, you can reference dynamic variables using {{variableName}} syntax:

System Prompt with Variables
You are a helpful customer support agent for {{companyName}}.
Your role:
- Answer questions about {{companyName}}'s products
- Help customers with their {{serviceType}} needs
- Escalate to human agents when needed
Current customer tier: {{customerTier}}
2

Pass variables in your chat request

Use assistantOverrides.variableValues to pass dynamic data:

Chat Request with Variables
$curl -X POST https://api.vapi.ai/chat \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "assistantId": "your-assistant-id",
>    "input": "I need help with my account",
>    "assistantOverrides": {
>      "variableValues": {
>        "companyName": "TechFlow Solutions",
>        "serviceType": "software",
>        "customerTier": "Premium"
>      }
>    }
>  }'

6. Integrate with TypeScript

1

Create a simple chat function

Here’s a TypeScript function you can use in your application:

chat.ts
1interface ChatMessage {
2  role: 'user' | 'assistant';
3  content: string;
4}
5
6interface ChatApiResponse {
7  id: string;
8  assistantId: string;
9  messages: ChatMessage[];
10  output: ChatMessage[];
11  createdAt: string;
12  updatedAt: string;
13  orgId?: string;
14  sessionId?: string;
15  name?: string;
16}
17
18interface ChatResponse {
19  chatId: string;
20  response: string;
21  fullData: ChatApiResponse;
22}
23
24async function sendChatMessage(
25  message: string, 
26  previousChatId?: string
27): Promise<ChatResponse> {
28  const response = await fetch('https://api.vapi.ai/chat', {
29    method: 'POST',
30    headers: {
31      'Authorization': 'Bearer YOUR_API_KEY',
32      'Content-Type': 'application/json'
33    },
34    body: JSON.stringify({
35      assistantId: 'your-assistant-id',
36      input: message,
37      ...(previousChatId && { previousChatId })
38    })
39  });
40
41  if (!response.ok) {
42    throw new Error(`HTTP error! status: ${response.status}`);
43  }
44
45  const chat: ChatApiResponse = await response.json();
46  return {
47    chatId: chat.id,
48    response: chat.output[0].content,
49    fullData: chat
50  };
51}
52
53// Usage example
54const firstMessage = await sendChatMessage("Hello, I need help");
55console.log(firstMessage.response);
56
57const followUp = await sendChatMessage("Tell me more", firstMessage.chatId);
58console.log(followUp.response);
2

Test your integration

Run your TypeScript code to verify the chat integration works correctly.

7. Test Your Chat Bot

1

Test various scenarios

Try these test cases to ensure your chat bot works correctly:

Test Case 1: General Question
$curl -X POST https://api.vapi.ai/chat \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "assistantId": "your-assistant-id",
>    "input": "What are your business hours?"
>  }'
Test Case 2: Technical Issue
$curl -X POST https://api.vapi.ai/chat \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "assistantId": "your-assistant-id",
>    "input": "My app keeps crashing when I try to export data"
>  }'
2

Verify conversation memory

Send follow-up messages using previousChatId to ensure context is maintained.

Limitations

Current chat functionality limitations:

  • “Query” tool for knowledge-base searches is not yet supported
  • Server webhook events (status updates, end-of-call reports, etc.) are not supported

Next Steps

Take your chat bot to the next level:

Need help? Chat with the team on our Discord or mention us on X/Twitter.