Skip to main content

​
Quickstart

This guide walks you through creating your first AI voice agent on thinnestAI. By the end, you’ll have an agent that can answer phone calls and chat with users.

​
Prerequisites

  • A thinnestAI account (sign up here)
  • A phone to test calls (optional — you can also test via the chat widget)

​
Step 1: Sign Up and Get Your API Key

  1. Go to app.thinnest.ai and create an account.
  2. After signing in, navigate to Settings > API Keys.
  3. Click Generate API Key and copy the key. Store it securely — you’ll need it for API calls.
# Save your API key as an environment variable
THINNESTAI_API_KEY=your-api-key-here

​
Step 2: Create Your First Agent

​
Via the Dashboard

  1. Click + New Agent from the dashboard.
  2. Fill in the basics:
    • Name: Give your agent a name (e.g., “Customer Support Agent”)
    • Model: Select a model (we recommend Claude or GPT-4 for voice agents)
    • Instructions: Tell the agent what it should do
  3. Write a simple instruction to start: 
You are a helpful customer support agent for Acme Corp.
Greet the caller warmly, ask how you can help, and answer
questions about our products and services. Be concise and
friendly. If you don't know the answer, offer to transfer
the caller to a human agent.
  1. Click Create Agent.

​
Via the API

curl -X POST https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "model": "claude-sonnet",
    "instructions": "You are a helpful customer support agent for Acme Corp. Greet the caller warmly, ask how you can help, and answer questions about our products and services.",
    "voice": "alloy"
  }'
The response includes your agent’s ID: 
{
  "id": "agent_abc123",
  "name": "Customer Support Agent",
  "status": "active"
}

​
Step 3: Assign a Phone Number

  1. Go to your agent’s settings page.
  2. Click the Phone tab.
  3. Choose one of:
    • Get a new number — Select a number from available options (US, UK, and other countries supported)
    • Bring your own number — Connect via SIP trunk configuration
  4. Once assigned, your agent is live and ready to take calls.

​
Via the API

# List available phone numbers
curl https://api.thinnest.ai/voice/phone-numbers/available \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"

# Assign a number to your agent
curl -X POST https://api.thinnest.ai/voice/phone-numbers/assign \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "phone_number": "+14155551234"
  }'

​
Step 4: Make Your First Call

Pick up your phone and call the number you just assigned. Your agent will answer and start a conversation based on the instructions you provided.

​
Trigger an Outbound Call via API

You can also have your agent call someone: 
curl -X POST https://api.thinnest.ai/calls/outbound \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "to": "+14155559876"
  }'

​
Step 5: Test with the Chat Widget

Don’t have a phone handy? You can test your agent directly in the dashboard:
  1. Go to your agent’s page.
  2. Click Test Chat in the top right.
  3. Type a message and see how your agent responds.

​
Embed the Chat Widget on Your Website

You can also embed the chat widget on any webpage: 
<script
  src="https://app.thinnest.ai/embed.js"
  data-agent-id="agent_abc123"
  data-theme="light"
  async
></script>
This adds a chat bubble to the bottom-right corner of your page.

​
What’s Next?

Now that your first agent is live, explore these guides to make it smarter:
  • Agents — Dive deeper into agent configuration and settings
  • Models — Learn about different AI models and when to use them
  • Prompts — Write better instructions for more effective agents
  • Memory — Configure how your agent remembers context across conversations

​
Troubleshooting

Agent not answering calls?
  • Verify the phone number is correctly assigned in the Phone tab.
  • Check that your agent’s status is “active” in the dashboard.
  • Ensure you have sufficient balance in your account.
Agent giving wrong answers?
  • Review and improve your system prompt. See Prompts for best practices.
  • Add relevant documents to the agent’s Knowledge Base.
API returning 401?
  • Double-check your API key is correct and hasn’t expired.
  • See Authentication for details.