TypeScript SDK

npm install @hookchat/node

import { HookChat } from '@hookchat/node'

const client = new HookChat({
  apiKey: process.env.HOOKCHAT_API_KEY!, // hookchat_live_... or hookchat_test_...
  baseUrl: process.env.HOOKCHAT_BASE_URL!, // the API origin, https://hookchat.dev by default
})

const { name, version, time } = await client.ping() // GET /v1/ping, unauthenticated
console.log('ok', name, version, time)

import { HookChat } from '@hookchat/node'

const client = new HookChat({ apiKey: process.env.HOOKCHAT_API_KEY!, baseUrl: process.env.HOOKCHAT_BASE_URL! })
const conversation_id = process.env.CONVERSATION_ID!

// Inside the 24 hour window.
const reply = await client.messages.reply({ conversation_id, text: 'Thanks, on it.' })
console.log('reply sent', reply.platform_message_id)

// Between 24 hours and 7 days, typed by a human. actor_id is required by the type.
const followUp = await client.messages.sendAsHumanAgent({ conversation_id, text: 'Following up.', actor_id: 'agent-7' })
console.log('human-agent sent', followUp.platform_message_id)

import { HookChat } from '@hookchat/node'

const client = new HookChat({ apiKey: process.env.HOOKCHAT_API_KEY!, baseUrl: process.env.HOOKCHAT_BASE_URL! })

const accounts = await client.accounts.list() // not paginated
for (const a of accounts) if (a.refresh_error) console.warn(a.handle, 'needs relinking:', a.refresh_error)

const stats = await client.stats.get()
console.log('messages_24h', stats.messages_24h, 'dlq_total', stats.dlq_total, 'endpoints', stats.endpoints.length)

const audit = await client.audit.list({ limit: 5 }) // most recent first
for (const entry of audit.audit) console.log(entry.at, entry.actor, entry.action, entry.resource)

const endpoints = await client.webhooks.list() // never returns a secret
console.log(endpoints.length, 'endpoints,', accounts.length, 'accounts')

import { HookChat, HookChatError } from '@hookchat/node'

const client = new HookChat({ apiKey: process.env.HOOKCHAT_API_KEY!, baseUrl: process.env.HOOKCHAT_BASE_URL! })

try {
  await client.messages.reply({ conversation_id: process.env.CLOSED_CONVERSATION_ID!, text: 'Hello again' })
} catch (error) {
  if (!(error instanceof HookChatError)) throw error
  switch (error.code) {
    case 'window_closed':
      console.log('refused:', error.code, 'status', error.status, 'request', error.requestId)
      break
    case 'rate_limited':
      // Back off; the SDK never retries a send.
      break
    case 'send_failed':
      // Meta refused; error.detail carries the reason and a retry may help.
      break
    default:
      throw error
  }
}

import { createServer } from 'node:http'
import { verifyWebhook, HookChatSignatureError } from '@hookchat/node'

const secret = process.env.WEBHOOK_SECRET!

createServer((req, res) => {
  const chunks: Buffer[] = []
  req.on('data', (chunk: Buffer) => chunks.push(chunk))
  req.on('end', () => {
    try {
      const event = verifyWebhook(Buffer.concat(chunks), req.headers, secret)
      if (event.type === 'message.received') {
        console.log('inbound', event.data.message.conversation_id, event.data.message.text)
      } else {
        console.log('verified', event.type, event.id)
      }
      res.writeHead(200).end()
    } catch (error) {
      if (error instanceof HookChatSignatureError) {
        res.writeHead(401).end()
        return
      }
      throw error
    }
  })
}).listen(Number(process.env.PORT))

import { HookChat } from '@hookchat/node'

const client = new HookChat({ apiKey: process.env.HOOKCHAT_API_KEY!, baseUrl: process.env.HOOKCHAT_BASE_URL! })

let unanswered = 0
for await (const c of client.conversations.iterate({ limit: 100, maxItems: 500 })) {
  if (c.unanswered && c.can_reply) unanswered += 1
}
console.log(unanswered, 'unanswered conversations still inside the window')

for await (const entry of client.audit.iterate({ maxItems: 3 })) console.log(entry.action, entry.resource)

import { HookChat } from '@hookchat/node'

const client = new HookChat({
  apiKey: process.env.HOOKCHAT_API_KEY!,
  baseUrl: process.env.HOOKCHAT_BASE_URL!,
  timeoutMs: 10_000,
  maxRetries: 3,
})

const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), 2_000)
const stats = await client.stats.get({}, { signal: controller.signal, timeoutMs: 5_000, maxRetries: 0 })
clearTimeout(timer)
console.log('window_hours', stats.window_hours)