Backend SDKs

Server-side SDKs for handling chat events, custom automation, and deep integrations.

Available SDKs

SDK	Language	Package
Node.js	JavaScript/TypeScript	@pocketping/sdk-node
Python	Python 3.10+	pocketping
Go	Go 1.21+	github.com/Ruwad-io/pocketping/sdk-go
PHP	PHP 8.1+	pocketping/sdk
Ruby	Ruby 3.1+	pocketping

When to Use an SDK

Use Case	SDK Needed?
Basic chat widget	❌ No - use SaaS or bridge-server only
Custom event tracking	✅ Yes
User identification	✅ Yes
Webhook forwarding	✅ Yes (or bridge-server env var)
Custom automation	✅ Yes
AI fallback	✅ Yes
Custom storage	✅ Yes

Core Features

1. Event Handling

React to widget events in your backend:

const pp = new PocketPing({
  onSessionStart: (session) => {
    analytics.track('chat_started', { country: session.metadata.country });
  },

  onMessage: (message, session) => {
    if (message.content.includes('urgent')) {
      notifyTeam('Urgent message!', session.id);
    }
  },

  onEvent: (event, session) => {
    if (event.name === 'clicked_pricing') {
      crm.updateLead(session.visitorId, { interest: 'pricing' });
    }
  },
});

2. Custom Events

Trigger events from the widget and handle them server-side:

// Widget (frontend)
PocketPing.trigger('viewed_pricing', { plan: 'pro' });

// SDK (backend)
pp.on('viewed_pricing', async (event, session) => {
  await analytics.track('pricing_view', event.data);

  // Send event back to widget
  await pp.emitEvent(session.id, 'show_discount', { percent: 10 });
});

3. Webhook Forwarding

Forward events to Zapier, Make, n8n, or custom endpoints:

const pp = new PocketPing({
  webhookUrl: 'https://hooks.zapier.com/hooks/catch/123/abc',
  webhookSecret: 'whsec_xxx', // HMAC signature
});

4. User Identification

Enrich sessions with user data so operators can see who they're talking to:

// After user logs in
await pp.handleIdentify({
  sessionId,
  identity: {
    id: user.id,                    // Required
    email: user.email,
    name: user.name,
    plan: user.subscription.plan,
    company: user.company.name,
  },
});

5. AI Fallback

Auto-respond when operators are away:

const pp = new PocketPing({
  aiProvider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
  aiTakeoverDelay: 300, // 5 minutes
  aiSystemPrompt: 'You are a helpful support assistant for Acme Inc...',
});

Architecture

Quick Start

Node.js

npm install @pocketping/sdk-node

const express = require('express');
const { PocketPing } = require('@pocketping/sdk-node');

const app = express();
const pp = new PocketPing({
  welcomeMessage: 'Hi! How can we help?',
});

app.use('/pocketping', pp.middleware());
app.listen(3000);

Python

pip install pocketping

from fastapi import FastAPI
from pocketping import PocketPing

app = FastAPI()
pp = PocketPing(welcome_message="Hi! How can we help?")

pp.mount_fastapi(app, prefix="/pocketping")

Go

go get github.com/Ruwad-io/pocketping/sdk-go

package main

import (
    "net/http"
    pocketping "github.com/Ruwad-io/pocketping/sdk-go"
)

func main() {
    pp := pocketping.New(pocketping.Config{
        WelcomeMessage: "Hi! How can we help?",
    })

    http.Handle("/pocketping/", pp.Handler("/pocketping"))
    http.ListenAndServe(":3000", nil)
}

PHP

composer require pocketping/sdk

<?php
use PocketPing\PocketPing;
use PocketPing\Models\ConnectRequest;

$pp = new PocketPing(
    welcomeMessage: 'Hi! How can we help?',
);

// Laravel — call the SDK handlers from your own routes
Route::post('/pocketping/connect', function (\Illuminate\Http\Request $request) use ($pp) {
    return response()->json($pp->handleConnect(ConnectRequest::fromArray($request->all())));
});

Ruby

gem install pocketping

require 'pocketping'

pp = PocketPing.new(welcome_message: 'Hi! How can we help?')

# Rails
Rails.application.routes.draw do
  mount pp.rack_app => '/pocketping'
end

SDK vs Bridge Server

Feature	SDK	Bridge Server Only
Message routing	✅	✅
Event handlers	✅	❌
User identification	✅	❌
Custom automation	✅	❌
Webhook forwarding	✅	✅ (via env var)
AI fallback	✅	✅ (via env var)
Custom storage	✅	❌

Use SDK when: You need custom logic, event handling, or deep integration.

Use Bridge Server only when: You just need basic chat → messaging platform routing.

Next Steps

• Node.js SDK - Full documentation
• Python SDK - Full documentation
• Go SDK - Full documentation
• PHP SDK - Full documentation
• Ruby SDK - Full documentation
• Webhook Forwarding - Zapier, Make, n8n integration
• Self-Hosting - Deploy your own backend