Skip to main content

Go SDK

Official HueChat SDK for Go applications.

Installation​

go get github.com/huechat/go-sdk

Requirements: Go 1.21+

Quick Start​

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/huechat/go-sdk"
)

func main() {
    client := huechat.NewClient(
        huechat.WithAPIKey(os.Getenv("HUECHAT_API_KEY")),
    )

    ctx := context.Background()

    // Create a contact
    contact, err := client.Contacts.Create(ctx, &huechat.CreateContactRequest{
        Phone:     "+1234567890",
        FirstName: "John",
        LastName:  "Doe",
    })
    if err != nil {
        panic(err)
    }

    // Send a message
    message, err := client.Messages.Send(ctx, contact.ID, &huechat.SendMessageRequest{
        Channel:     "whatsapp",
        MessageType: "text",
        Content:     "Hello from HueChat!",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Message sent: %s\n", message.ID)
}

Configuration​

Basic Setup​

client := huechat.NewClient(
    huechat.WithAPIKey("sk_live_your_key"),
)

With Options​

client := huechat.NewClient(
    huechat.WithAPIKey(os.Getenv("HUECHAT_API_KEY")),
    huechat.WithBaseURL("https://api.huechat.ai/v2"),
    huechat.WithTimeout(30*time.Second),
    huechat.WithRetries(3),
    huechat.WithDebug(true),
)

Custom HTTP Client​

httpClient := &http.Client{
    Timeout: 60 * time.Second,
    Transport: &http.Transport{
        MaxIdleConns:    10,
        IdleConnTimeout: 30 * time.Second,
    },
}

client := huechat.NewClient(
    huechat.WithAPIKey(os.Getenv("HUECHAT_API_KEY")),
    huechat.WithHTTPClient(httpClient),
)

Contacts​

Create Contact​

contact, err := client.Contacts.Create(ctx, &huechat.CreateContactRequest{
    Phone:            "+1234567890",
    Email:            "john@example.com",
    FirstName:        "John",
    LastName:         "Doe",
    PreferredChannel: "whatsapp",
    Metadata: map[string]interface{}{
        "customer_id": "cust_123",
        "plan":        "premium",
    },
})

Get Contact​

// By ID
contact, err := client.Contacts.Get(ctx, "cnt_abc123")

// By phone
contact, err := client.Contacts.Get(ctx, "+1234567890")

// By email
contact, err := client.Contacts.Get(ctx, "john@example.com")

Update Contact​

updated, err := client.Contacts.Update(ctx, "cnt_abc123", &huechat.UpdateContactRequest{
    FirstName: "Johnny",
    Metadata: map[string]interface{}{
        "plan": "enterprise",
    },
})

Delete Contact​

err := client.Contacts.Delete(ctx, "cnt_abc123")

Get Contact Conversations​

conversations, err := client.Contacts.Conversations(ctx, "cnt_abc123", &huechat.ListConversationsParams{
    Status: "open",
    Limit:  20,
})

for _, conv := range conversations.Data {
    fmt.Printf("%s: %s\n", conv.Contact.FullName, conv.LastMessagePreview)
}

Messages​

Send Text Message​

message, err := client.Messages.Send(ctx, "cnt_abc123", &huechat.SendMessageRequest{
    Channel:     "whatsapp",
    MessageType: "text",
    Content:     "Hello! How can I help you today?",
})

Send Template Message​

message, err := client.Messages.Send(ctx, "cnt_abc123", &huechat.SendMessageRequest{
    Channel:      "whatsapp",
    MessageType:  "template",
    TemplateName: "order_confirmation",
    TemplateParameters: map[string]string{
        "order_id":      "ORD-12345",
        "total":         "$99.99",
        "delivery_date": "January 27",
    },
})

Send Media Message​

// Image
message, err := client.Messages.Send(ctx, "cnt_abc123", &huechat.SendMessageRequest{
    Channel:     "whatsapp",
    MessageType: "image",
    MediaURL:    "https://example.com/image.jpg",
    Content:     "Check out this product!",
})

// Document
message, err := client.Messages.Send(ctx, "cnt_abc123", &huechat.SendMessageRequest{
    Channel:     "whatsapp",
    MessageType: "document",
    MediaURL:    "https://example.com/invoice.pdf",
    Content:     "Here is your invoice",
})

Conversations​

List Conversations​

conversations, err := client.Conversations.List(ctx, &huechat.ListConversationsParams{
    Status:  "open",
    Channel: "whatsapp",
    Limit:   50,
})

for _, conv := range conversations.Data {
    fmt.Printf("%s: %s\n", conv.Contact.FullName, conv.LastMessagePreview)
}

Get Conversation​

conversation, err := client.Conversations.Get(ctx, "conv_xyz789")

Get Messages​

messages, err := client.Conversations.Messages(ctx, "conv_xyz789", &huechat.ListMessagesParams{
    Limit: 100,
    Sort:  "created_at:asc",
})

Send Message in Conversation​

message, err := client.Conversations.SendMessage(ctx, "conv_xyz789", &huechat.SendMessageRequest{
    MessageType: "text",
    Content:     "Thanks for your patience!",
})

Assign Conversation​

err := client.Conversations.Assign(ctx, "conv_xyz789", &huechat.AssignConversationRequest{
    AssignedTo:   "usr_agent1",
    InternalNote: "Please handle this VIP customer",
})

Add Labels​

err := client.Conversations.AddLabels(ctx, "conv_xyz789", []string{"urgent", "billing"})

Resolve Conversation​

err := client.Conversations.Resolve(ctx, "conv_xyz789", &huechat.ResolveConversationRequest{
    ResolutionReason:       "issue_resolved",
    InternalNote:           "Refund processed",
    SendSatisfactionSurvey: true,
})

Webhooks​

Create Webhook​

webhook, err := client.Webhooks.Create(ctx, &huechat.CreateWebhookRequest{
    URL:    "https://your-server.com/webhooks/huechat",
    Events: []string{"message.received", "conversation.created"},
})

// Save the signing secret!
fmt.Printf("Signing secret: %s\n", webhook.SigningSecret)

Verify Signature​

import "github.com/huechat/go-sdk/webhook"

func WebhookHandler(w http.ResponseWriter, r *http.Request) {
    payload, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-HueChat-Signature")
    timestamp := r.Header.Get("X-HueChat-Timestamp")

    if !webhook.Verify(payload, signature, timestamp, os.Getenv("HUECHAT_WEBHOOK_SECRET")) {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    var event huechat.WebhookEvent
    json.Unmarshal(payload, &event)

    switch event.Type {
    case "message.received":
        // Handle new message
    case "conversation.created":
        // Handle new conversation
    }

    w.WriteHeader(http.StatusOK)
}

Error Handling​

contact, err := client.Contacts.Create(ctx, &huechat.CreateContactRequest{
    Phone: "invalid-phone",
})

if err != nil {
    switch e := err.(type) {
    case *huechat.BadRequestError:
        fmt.Printf("Validation error: %s\n", e.Message)
        fmt.Printf("Details: %v\n", e.Details)
    case *huechat.UnauthorizedError:
        fmt.Println("Invalid API key")
    case *huechat.NotFoundError:
        fmt.Println("Resource not found")
    case *huechat.RateLimitError:
        fmt.Printf("Rate limited, retry after: %d seconds\n", e.RetryAfter)
    default:
        fmt.Printf("Error: %v\n", err)
    }
}

Gin Integration​

package main

import (
    "os"

    "github.com/gin-gonic/gin"
    "github.com/huechat/go-sdk"
    "github.com/huechat/go-sdk/webhook"
)

var client = huechat.NewClient(
    huechat.WithAPIKey(os.Getenv("HUECHAT_API_KEY")),
)

func main() {
    r := gin.Default()

    r.POST("/webhooks/huechat", func(c *gin.Context) {
        payload, _ := c.GetRawData()
        signature := c.GetHeader("X-HueChat-Signature")
        timestamp := c.GetHeader("X-HueChat-Timestamp")

        if !webhook.Verify(payload, signature, timestamp, os.Getenv("HUECHAT_WEBHOOK_SECRET")) {
            c.JSON(401, gin.H{"error": "Invalid signature"})
            return
        }

        var event huechat.WebhookEvent
        if err := c.ShouldBindJSON(&event); err != nil {
            c.JSON(400, gin.H{"error": err.Error()})
            return
        }

        // Handle event
        switch event.Type {
        case "message.received":
            handleNewMessage(event.Data)
        }

        c.Status(200)
    })

    r.Run(":8080")
}

Echo Integration​

package main

import (
    "io"
    "os"

    "github.com/labstack/echo/v4"
    "github.com/huechat/go-sdk"
    "github.com/huechat/go-sdk/webhook"
)

func main() {
    e := echo.New()

    e.POST("/webhooks/huechat", func(c echo.Context) error {
        payload, _ := io.ReadAll(c.Request().Body)
        signature := c.Request().Header.Get("X-HueChat-Signature")
        timestamp := c.Request().Header.Get("X-HueChat-Timestamp")

        if !webhook.Verify(payload, signature, timestamp, os.Getenv("HUECHAT_WEBHOOK_SECRET")) {
            return c.JSON(401, map[string]string{"error": "Invalid signature"})
        }

        // Process event...

        return c.NoContent(200)
    })

    e.Start(":8080")
}