Skip to main content
Docs menu: Quickstart

Get started

Quickstart

Create an API key, have your agent call a phone you can answer, and read the result when the call ends.

You need a Telvana workspace with an agent that has a phone number and an outbound prompt, the script the agent follows on calls it places. We set these up with you when we build your agent. You sign in to the portal at app.telvana.com.

1. Create an API key

In the portal, open Settings, then API Keys, and choose Create API Key. Name it after where it will run, such as "Production server".

The portal shows the key once. Telvana stores only a hash of it, so copy it now and keep it in your secrets manager or an environment variable:

export TELVANA_API_KEY="paste-your-key-here"

2. Find your agent's number

Open Phone Numbers in the portal and note the number assigned to your agent. That number goes in from, and it decides which agent places the call. Write numbers in E.164 form: a plus sign, the country code and the number, such as +15551234567.

3. Place a call

Put your agent's number in from and a phone you can answer in to:

curl -X POST "https://api.telvana.com/outbound" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "variables": { "firstName": "Dana" }
  }'

Telvana queues the call and answers with the id the call's conversation will have:

{
  "data": {
    "from": "+15551234567",
    "to": "+15557654321",
    "conversationId": "clx8y9z1a2b3c4d5e6f7g8h9i",
    "variables": { "firstName": "Dana" }
  },
  "message": "Request queued for outbound processing"
}

Answer when your phone rings and talk to the agent. variables fills placeholders such as {{firstName}} in the agent's outbound prompt; Placing outbound calls covers them.

4. Read the result

When the call ends, Telvana analyzes it and stores the conversation. Fetch it with the id from step 3:

curl "https://api.telvana.com/conversation/clx8y9z1a2b3c4d5e6f7g8h9i" \
  -H "x-api-key: $TELVANA_API_KEY"

The response has the transcript, a summary, the sentiment, any tags and a link to the recording. While the call is still going, data is null.

Polling works for a test. In production, turn on the post-conversation webhook instead, and Telvana sends each result to your server as soon as the call ends.

Next steps