Skip to content

Go SDK

The official Go SDK for backend integration with the Uchara Chat Platform.

Installation

go get github.com/Uchara-AI/sdk-go

Requirements

Go 1.19+

Server SDK

The Go SDK focuses on server-to-server integration.

package main

import (
    "context"
    "log"
    "os"

    "github.com/Uchara-AI/sdk-go"
)

func main() {
    client := uchara.NewServerSDK(uchara.ServerConfig{
        APIURL: "https://api.uchara.com",
        APIKey: os.Getenv("UCHARA_API_KEY"),
    })

    ctx := context.Background()

    // Send a message
    msg, err := client.SendMessage(ctx, "conv_abc123", uchara.SendMessageRequest{
        Content:    "Your order has shipped!",
        SenderType: "bot",
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Message sent: %s", msg.ID)
}

Methods

Contacts

// Upsert contact
contact, err := client.UpsertContact(ctx, uchara.CreateContactRequest{
    ExternalID: "user_123",
    Name:       "John Doe",
    Email:      "john@example.com",
})

// Get contact
contact, err := client.GetContact(ctx, "contact_id")

// List contacts
contacts, err := client.ListContacts(ctx, 10, 0, "search_query")

Conversations

// List conversations
convs, err := client.ListConversations(ctx, uchara.ListConversationsOptions{
    Status: uchara.StatusOpen,
    Limit:  10,
})

// Get conversation
conv, err := client.GetConversation(ctx, "conv_id")

// Assign
agentID := "agent_123"
err := client.AssignConversation(ctx, "conv_id", &agentID)

// Resolve
err := client.ResolveConversation(ctx, "conv_id")

Messages

// Send message
msg, err := client.SendMessage(ctx, "conv_id", uchara.SendMessageRequest{
    Content:    "Hello!",
    SenderType: "bot",
})

// Get messages
msgs, err := client.GetMessages(ctx, "conv_id", 50, "")

Error Handling

import "errors"

msg, err := client.SendMessage(ctx, "conv_id", req)
if err != nil {
    var apiErr *uchara.APIError
    if errors.As(err, &apiErr) {
        log.Printf("API error %d: %s", apiErr.Status, apiErr.Message)

        switch apiErr.Status {
        case 401:
            // Invalid API key
        case 429:
            // Rate limited
        }
    }
}

Context & Timeouts

All methods accept a context.Context for cancellation and timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

msg, err := client.SendMessage(ctx, "conv_id", req)

Configuration

client := uchara.NewServerSDK(uchara.ServerConfig{
    APIURL:      "https://api.uchara.com",
    APIKey:      os.Getenv("UCHARA_API_KEY"),
    WorkspaceID: "optional_workspace_id",
    Timeout:     30 * time.Second, // Default: 30s
})

Complete Example: E-commerce Integration

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/Uchara-AI/sdk-go"
)

func notifyOrderShipped(orderID, conversationID string) error {
    client := uchara.NewServerSDK(uchara.ServerConfig{
        APIURL: "https://api.uchara.com",
        APIKey: os.Getenv("UCHARA_API_KEY"),
    })

    ctx := context.Background()

    _, err := client.SendMessage(ctx, conversationID, uchara.SendMessageRequest{
        Content: fmt.Sprintf(
            "🚚 Your order #%s has shipped! Track: https://track.example.com/%s",
            orderID, orderID,
        ),
        SenderType: "bot",
    })

    return err
}

Resources