> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vatel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Use the Vatel REST and WebSocket APIs from Go. Run real-time voice sessions and access the API with a single client.

Use the **Vatel Go SDK** to call the REST and WebSocket APIs from Go. One client handles both: REST for your organization and WebSocket for real-time voice sessions: receive events, send input audio, and handle tool calls.

<Card title="Session token" icon="key" href="/api-reference/session/session-token">
  REST endpoint used to obtain a short-lived JWT for the WebSocket connection.
</Card>

<Card title="Connection" icon="radio" href="/api-reference/session/connection">
  WebSocket channel, message types, and request/response flow.
</Card>

## Prerequisites

* **Go** 1.21+
* **Organization API key** from the Vatel dashboard
* **Agent ID** (agent UUID) for the agent you want to run the call with

## Walkthrough

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    go get github.com/Devpro-Software/vatel-go-sdk
    ```
  </Step>

  <Step title="Create a client and get a session token">
    Create a client with the API base URL and your API key, then obtain a session token for the agent:

    ```go theme={null}
    client := vatel.New("https://api.vatel.ai", "your-org-api-key")
    ctx := context.Background()

    tokenResp, err := client.SessionToken(ctx, "agent-uuid")
    if err != nil {
        log.Fatal(err)
    }
    ```
  </Step>

  <Step title="Open the WebSocket connection">
    Dial the connection with the token and consume messages:

    ```go theme={null}
    conn, err := client.DialConnection(ctx, tokenResp.Token)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    for msg := range conn.Messages() {
        data, _ := msg.ParseData()
        switch msg.Type {
        case vatel.TypeSessionStarted:
            if d, ok := data.(vatel.SessionStartedData); ok {
                log.Println("session started", d.ID)
            }
        case vatel.TypeResponseAudio:
            if d, ok := data.(vatel.ResponseAudioData); ok {
                // Decode d.Audio (base64) and play PCM 16 24kHz mono
                _ = d
            }
        case vatel.TypeToolCall:
            if d, ok := data.(vatel.ToolCallData); ok {
                conn.SendToolCallOutput(d.ToolCallID, "result")
            }
        case vatel.TypeSessionEnded:
            return
        }
    }
    ```
  </Step>

  <Step title="Send audio">
    Send microphone (or other) audio as PCM 16-bit 24 kHz mono. Use base64 or raw bytes:

    ```go theme={null}
    conn.SendInputAudio(base64PCM)
    // or
    conn.SendInputAudioBytes(pcm)
    ```
  </Step>
</Steps>

## REST API

The same client exposes the REST API. See the [API reference](/api-reference) for all endpoints. You can pass a custom HTTP client:

```go theme={null}
client := vatel.New("https://api.vatel.ai", apiKey, vatel.WithHTTPClient(myHTTPClient))
```

## WebSocket (call session)

After you have a session token:

1. **Connect** - `client.DialConnection(ctx, tokenResp.Token)` opens the WebSocket. For a custom dialer, use `client.ConnectionURL(token)` and `vatel.DialConnection(ctx, url, nil)`.
2. **Send** - `conn.SendInputAudio(base64PCM)` or `conn.SendInputAudioBytes(pcm)` for input audio; `conn.SendToolCallOutput(toolCallID, output)` for tool results.
3. **Receive** - `conn.Receive()` for one message, or `conn.Messages()` for a channel. Use `msg.ParseData()` to get typed structs (`SessionStartedData`, `ResponseAudioData`, `ToolCallData`, etc.).

When done, call `conn.Close()` or `conn.CloseWithReason(code, text)`.

## Error handling

* REST errors are returned as `*vatel.APIError` with `StatusCode` and `Body`. Use them to handle 4xx/5xx responses.
* Sending on a closed WebSocket returns `vatel.ErrConnectionClosed`.