Webex Go SDK

A comprehensive, lightweight Go SDK for Cisco Webex API

Implementation Status

• ✅ All REST APIs are fully implemented and working
• ✅ WebSocket APIs with end-to-end encrypted message decryption
• ✅ Real-time Webex Calling with WebRTC media (Mobius/BroadWorks)

Installation

go get github.com/WebexCommunity/webex-go-sdk/v2

Quick Start

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/WebexCommunity/webex-go-sdk/v2"
)

func main() {
    // Get access token from environment
    accessToken := os.Getenv("WEBEX_ACCESS_TOKEN")
    if accessToken == "" {
        log.Fatal("WEBEX_ACCESS_TOKEN environment variable is required")
    }

    // Create client
    client, err := webex.NewClient(accessToken, nil)
    if err != nil {
        log.Fatalf("Error creating client: %v", err)
    }

    // Get my own details
    me, err := client.People().GetMe()
    if err != nil {
        log.Fatalf("Error getting my details: %v", err)
    }

    fmt.Printf("Hello, %s!\n", me.DisplayName)
}

Supported APIs

REST APIs (Fully Implemented)

• People - Manage users in your organization
• Messages - Send and receive messages in rooms
• Rooms - Create and manage Webex rooms
• Teams - Create and manage Webex teams
• Team Memberships - Add and remove people from teams
• Memberships - Add and remove people from rooms
• Webhooks - Register for notifications
• Attachment Actions - Handle interactive card submissions
• Events - Subscribe to Webex events
• Room Tabs - Manage tabs in Webex rooms
• Meetings - Create, list, update, and delete Webex meetings
• Meeting Transcripts - List, download, and manage meeting transcripts and snippets
• Recordings - List, get, download (audio/video/transcript), and delete meeting recordings
• Contents - Download file attachments with anti-malware scanning support
• Calling - Call history, call settings (DND, call waiting, call forwarding, voicemail), contacts

WebSocket APIs

• Mercury - Real-time WebSocket connection with automatic reconnection
• Conversation Events - Listen for messages, shares, and acknowledgements
• End-to-End Encryption - Full JWE decryption using KMS (ECDH key exchange + AES-256-GCM)

Real-Time Call Control (Webex Calling)

• CallingClient - Line registration with Mobius, call lifecycle management, Mercury event routing
• AudioBridge - Browser-facing WebRTC PeerConnection with bidirectional RTP relay (PCMU/PCMA)
• Call Control - Dial, answer, hold, resume, transfer (blind/consult), DTMF, mute/unmute
• SignalingTransport - Transport-agnostic WebRTC signaling interface (WebSocket, gRPC, etc.)
• Address Normalization - Phone number sanitization and SIP/tel URI handling

Configuration

Customise client behaviour by passing a webexsdk.Config:

import (
    "time"

    "github.com/WebexCommunity/webex-go-sdk/v2"
    "github.com/WebexCommunity/webex-go-sdk/v2/webexsdk"
)

client, err := webex.NewClient(accessToken, &webexsdk.Config{
    BaseURL:        "https://webexapis.com/v1", // Default
    Timeout:        30 * time.Second,           // HTTP client timeout
    MaxRetries:               5,               // Default: 3 (0 disables retries)
    RetryBaseDelay:           2 * time.Second, // Default: 1s (exponential backoff)
    RetryUnsafeMethods:      false,           // Opt in only if duplicate side effects are acceptable
    DisableRetryAfterRetries: false,           // Return 429/423 immediately when true
})

See webexsdk/Readme.md for all configuration fields.

Automatic Retry & Resilience

The SDK automatically retries requests that receive transient error responses:

Status	Meaning	Retry Behaviour
429	Too Many Requests	Respects Retry-After header
423	Locked (file scanning)	Respects Retry-After header
502	Bad Gateway	Exponential backoff for idempotent methods
503	Service Unavailable	Exponential backoff for idempotent methods
504	Gateway Timeout	Exponential backoff for idempotent methods

Backoff formula: RetryBaseDelay × 2^attempt (e.g., 1s → 2s → 4s).

All request methods (Request, RequestURL, RequestMultipart) include retry support. By default, non-idempotent methods such as POST and PATCH are not retried after 502, 503, or 504 because the server may have completed the operation before returning an ambiguous error. Set RetryUnsafeMethods to true only when duplicate side effects are acceptable. Explicit Retry-After responses (429 and 423) remain retryable for all methods.

Queue consumers that need to release their message lock and schedule rate-limited work later should set DisableRetryAfterRetries to true, inspect the returned RateLimitError.RetryAfter, and perform the retry in their durable queue rather than blocking inside the SDK.

Error Handling

API errors are returned as structured types from the webexsdk package. Use convenience functions to inspect error types:

room, err := client.Rooms().Get("invalid-id")
if err != nil {
    switch {
    case webexsdk.IsNotFound(err):
        log.Println("Room not found")
    case webexsdk.IsAuthError(err):
        log.Println("Invalid access token")
    case webexsdk.IsRateLimited(err):
        log.Println("Rate limited — the SDK already retried")
    case webexsdk.IsServerError(err):
        log.Println("Server error — the SDK already retried")
    default:
        log.Printf("Error: %v", err)
    }
}

Available checkers: IsAuthError, IsForbidden, IsNotFound, IsConflict, IsGone, IsLocked, IsPreconditionRequired, IsRateLimited, IsServerError.

See webexsdk/Readme.md for the full error type reference.

Pagination

List endpoints return paginated results. Each module's List method returns a page with HasNext/Next() support:

page, err := client.Rooms().List(&rooms.ListOptions{Max: 50})
if err != nil {
    log.Fatal(err)
}

for {
    for _, room := range page.Items {
        fmt.Println(room.Title)
    }
    if !page.HasNext {
        break
    }
    page, err = page.Next()
    if err != nil {
        log.Fatal(err)
    }
}

Examples

See the examples directory.

• Calling Example - Web-based call control with browser audio bridge

Sending a Message

message := &messages.Message{
    RoomID: "ROOM_ID",
    Text:   "Hello, World!",
}

createdMessage, err := client.Messages().Create(message)
if err != nil {
    log.Fatalf("Error sending message: %v", err)
}
fmt.Printf("Message sent: ID=%s\n", createdMessage.ID)

Documentation

For detailed documentation, examples, and API reference, see:

• Go Reference Documentation
• Examples Directory
• Cisco Webex API Documentation

Requirements

• Go 1.21 or later

Questions, Support & Discussion

webex-go-sdk is a community developed and community-supported project. If you experience any issues using this package, please report them using the issues page.

Please join the Webex Go SDK - Community Contributors Webex space to ask questions, join the discussion, and share your projects and creations.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Add your name to CONTRIBUTORS.md if not already present
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

See CONTRIBUTORS.md for the list of contributors.

License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE.