> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Go SDK

> Install and use the voicebip-go module — auto-generated from the OpenAPI spec via Fern.

The official Voicebip SDK for Go, auto-generated from the OpenAPI spec via Fern. The module is not yet published — this page previews what the API will look like when it ships.

## Installation (Coming Soon)

```bash
go get github.com/voicebip/voicebip-go
```

Requires Go 1.22+.

## In the Meantime

Use the REST API directly with `net/http`:

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

const apiKey = "pk_live_xxx"
const baseURL = "https://api.voicebip.com/v1"

func voicebipPost(path string, body any) (map[string]any, error) {
	b, _ := json.Marshal(body)
	req, _ := http.NewRequest("POST", baseURL+path, bytes.NewReader(b))
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	var out map[string]any
	json.Unmarshal(raw, &out)
	return out, nil
}

func main() {
	agent, _ := voicebipPost("/agents", map[string]any{
		"display_name":  "Support",
		"language":      "en",
		"system_prompt": "You are a helpful agent.",
	})
	fmt.Println("agent_id:", agent["agent_id"])
}
```

## Preview Usage

When `voicebip-go` is published, the same flow will look like this:

## Quick start

```go
package main

import (
	"context"
	"fmt"
	"log"

	voicebip "github.com/voicebip/voicebip-go"
	"github.com/voicebip/voicebip-go/option"
)

func main() {
	client := voicebip.NewClient(
		option.WithAPIKey("pk_live_xxx"),
	)

	// Create an agent
	agent, err := client.Agents.Create(context.Background(), &voicebip.CreateAgentRequest{
		DisplayName:  "Customer Support",
		Language:     "en",
		SystemPrompt: voicebip.String("You are a helpful customer support agent."),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Agent:", agent.AgentID)

	// Initiate an outbound call
	call, err := client.Calls.Initiate(context.Background(), &voicebip.InitiateCallRequest{
		AgentID:    agent.AgentID,
		FromNumber: "+234800000xxxx",
		ToNumber:   "+2348031234567",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Call started:", call.CallID)
}
```

## Mint a WebRTC token (server-side)

Use `client.Webrtc.CreateToken` to mint a short-lived scoped token for a browser call, then return it to the browser so `@voicebip/web` can start the call.

```go
import voicebip "github.com/voicebip/voicebip-go"

func voiceTokenHandler(w http.ResponseWriter, r *http.Request) {
	var body struct {
		AgentID string `json:"agent_id"`
	}
	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	ttl := 600
	resp, err := vbClient.Webrtc.CreateToken(r.Context(), &voicebip.CreateWebRTCTokenRequest{
		AgentID:    body.AgentID,
		TtlSeconds: &ttl,
	})
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	json.NewEncoder(w).Encode(resp)
}
```

## Error handling

```go
import (
	voicebip "github.com/voicebip/voicebip-go"
	voicebipErr "github.com/voicebip/voicebip-go/errors"
)

_, err := client.Calls.Initiate(ctx, req)
if err != nil {
	var apiErr *voicebipErr.APIError
	if errors.As(err, &apiErr) {
		fmt.Printf("error_code: %s, message: %s\n", apiErr.ErrorCode, apiErr.Message)
		switch apiErr.ErrorCode {
		case "WORKSPACE_BLOCKED":
			// handle zero-balance state
		case "CALL_WINDOW_RESTRICTED":
			// outside permitted hours
		}
	}
}
```

## Configuration

```go
client := voicebip.NewClient(
	option.WithAPIKey("pk_live_xxx"),
	option.WithBaseURL("https://api.voicebip.com"), // default; change for sandbox
	option.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)
```

Use `pk_test_xxx` API keys to hit the sandbox — no real calls, no billing.

## Available methods

| Package    | Methods                                                            | Notes                  |
| ---------- | ------------------------------------------------------------------ | ---------------------- |
| `Agents`   | `Create`, `List`, `Get`, `Update`, `Delete`                        | Agent CRUD             |
| `Numbers`  | `ListAvailable`, `Provision`, `Get`, `Release`                     | Number management      |
| `Calls`    | `Initiate`, `Get`, `End`, `Hold`, `Resume`, `Transfer`, `SendDtmf` | Voice calls            |
| `Messages` | `Send`                                                             | SMS and WhatsApp       |
| `Webrtc`   | `CreateToken`, `CreateOffer`                                       | Browser call signaling |
| `ApiKeys`  | `Create`, `List`, `Revoke`, `Rotate`                               | API key management     |
| `Billing`  | `GetUsage`, `GetBalance`, `CreateCheckout`                         | Usage and payments     |
| `Dpa`      | `Accept`, `GetStatus`                                              | NDPR compliance        |
| `Webhooks` | `Test`                                                             | Webhook testing        |