Trials

curl -sS -X POST "https://api.isnap.ai/v1/trial/init" \
  -H "Authorization: Bearer $ISNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_outbound_without_inbound":10,"welcome_message":"You are connected. Reply to this message at any time.","metadata":{"crm_contact_id":"c_123"}}'

import { setTimeout as sleep } from 'node:timers/promises'
import { APIError, ISnapClient } from '@isnap/sdk'

const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY ?? '', maxRetries: 2 })

// A 503 with one of these codes starts no trial: the call is safe to make again.
const NO_TRIAL_STARTED = new Set(['line_pool_exhausted', 'pairing_code_unavailable'])

async function startTrial() {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.trial.init(
        {
          max_outbound_without_inbound: 10,
          welcome_message: 'You are connected. Reply to this message at any time.',
          metadata: { crm_contact_id: 'c_123' }
        },
        // The operation does not honor Idempotency-Key: the SDK must not retry it on its own.
        { maxRetries: 0 }
      )
    } catch (err) {
      if (err instanceof APIError && NO_TRIAL_STARTED.has(err.code) && attempt < 2) {
        await sleep(1000 * 2 ** (attempt + 1))
        continue
      }
      throw err
    }
  }
}

try {
  const trial = await startTrial()
  // Store trial.trial_id and trial.token, then show trial.token and
  // trial.pool_line_number to the prospect. Do not log the pairing code.
  console.log(trial.trial_id, trial.pairing_expires_at)
} catch (err) {
  if (err instanceof APIError && err.code === 'trial_already_active') {
    // A direct account has one live trial at a time.
    console.error('This account already has a live trial.')
  } else if (err instanceof APIError && NO_TRIAL_STARTED.has(err.code)) {
    // Write to support@isnap.ai with these two ids.
    console.error(`No trial was started: trace_id ${err.traceId}, request_id ${err.requestId}`)
  } else {
    throw err
  }
}

import os
import time

import requests

# A 503 with one of these codes starts no trial: the call is safe to make again.
NO_TRIAL_STARTED = ("line_pool_exhausted", "pairing_code_unavailable")

for attempt in range(3):
    if attempt > 0:
        time.sleep(2**attempt)
    response = requests.post(
        "https://api.isnap.ai/v1/trial/init",
        headers={"Authorization": f"Bearer {os.environ['ISNAP_API_KEY']}"},
        json={
            "max_outbound_without_inbound": 10,
            "welcome_message": "You are connected. Reply to this message at any time.",
            "metadata": {"crm_contact_id": "c_123"},
        },
        timeout=30,
    )
    payload = response.json()
    if response.status_code != 503 or payload["error"]["code"] not in NO_TRIAL_STARTED:
        break

if response.status_code == 201:
    trial = payload["data"]
    # Store trial["trial_id"] and trial["token"], then show trial["token"] and
    # trial["pool_line_number"] to the prospect. Do not log the pairing code.
    print(trial["trial_id"], trial["pairing_expires_at"])
elif payload["error"]["code"] == "trial_already_active":
    # A direct account has one live trial at a time.
    print("This account already has a live trial.")
elif payload["error"]["code"] in NO_TRIAL_STARTED:
    # Write to support@isnap.ai with these two ids.
    print("No trial was started:", payload["trace_id"], payload["request_id"])
else:
    # The operation does not honor Idempotency-Key: do not retry it blindly.
    response.raise_for_status()

# No credential: the pairing code identifies the trial. Run this from your backend only.
curl -sS "https://api.isnap.ai/v1/trial/status?token=K7MQ2XB"

import { APIError, ISnapClient } from '@isnap/sdk'

// The SDK needs a key even for an operation that requires none.
const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY ?? '', maxRetries: 2 })

type TrialRead =
  | { state: 'key'; trialKey: string; lineId: string; to: string }
  | { state: 'waiting' } // the prospect has not paired
  | { state: 'paired' } // the key was returned by an earlier call, or its hour has passed
  | { state: 'ended' } // the pairing window ended, the trial is revoked, or the code is unknown

// Call this from your backend when trial.linked arrives. `token` is the pairing code.
async function readTrial(token: string): Promise<TrialRead> {
  try {
    // Never retried: a retry after a lost response loses the trial key.
    const trial = await client.trial.status(token, { maxRetries: 0 })
    if (trial.status === 'pairing_pending') return { state: 'waiting' }
    if (trial.trial_api_key && trial.pool_line_id && trial.paired_handle) {
      return {
        state: 'key',
        trialKey: trial.trial_api_key,
        lineId: trial.pool_line_id,
        to: trial.paired_handle
      }
    }
    return { state: 'paired' }
  } catch (err) {
    if (err instanceof APIError && (err.code === 'pairing_expired' || err.code === 'trial_not_found')) {
      return { state: 'ended' }
    }
    throw err
  }
}

const read = await readTrial('K7MQ2XB')
// Never log the trial key, the pairing code or the paired handle.
console.log(read.state)

import requests


def read_trial(token):
    """Call this from your backend when trial.linked arrives. `token` is the pairing code."""
    # Never retried: a retry after a lost response loses the trial key.
    response = requests.get(
        "https://api.isnap.ai/v1/trial/status",
        params={"token": token},
        timeout=30,
    )
    payload = response.json()

    if response.status_code == 200:
        trial = payload["data"]
        if trial["status"] == "pairing_pending":
            return {"state": "waiting"}
        if "trial_api_key" in trial:
            return {
                "state": "key",
                "trial_key": trial["trial_api_key"],
                "line_id": trial["pool_line_id"],
                "to": trial["paired_handle"],
            }
        # The key was returned by an earlier call, or its hour has passed.
        return {"state": "paired"}

    if payload["error"]["code"] in ("pairing_expired", "trial_not_found"):
        # The pairing window ended, the trial is revoked, or the code is unknown.
        return {"state": "ended"}
    response.raise_for_status()


read = read_trial("K7MQ2XB")
# Never log the trial key, the pairing code or the paired handle.
print(read["state"])

# One key per message, unique across all your trials.
IDEMPOTENCY_KEY=$(uuidgen) # Store it with your record of the message: reuse it to retry.
curl -sS -X POST "https://api.isnap.ai/v1/messages" \
  -H "Authorization: Bearer $ISNAP_TRIAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"line_id":"line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd","to":"+14155550123","body":"Thanks for trying this out. Reply to this message to continue."}'

import { randomUUID } from 'node:crypto'
import { APIError, ISnapClient } from '@isnap/sdk'

// A client has one credential: this one sends with the trial key.
const trialClient = new ISnapClient({ apiKey: process.env.ISNAP_TRIAL_KEY ?? '', maxRetries: 2 })

// One key per message, unique across all your trials.
const idempotencyKey = randomUUID() // Store it with your record of the message: reuse it to retry.

try {
  const message = await trialClient.messages.send(
    {
      line_id: 'line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd', // pool_line_id of the trial
      to: '+14155550123', // paired_handle of the trial
      body: 'Thanks for trying this out. Reply to this message to continue.'
    },
    { idempotencyKey }
  )
  console.log(message.id, message.status)
} catch (err) {
  if (!(err instanceof APIError)) throw err
  switch (err.code) {
    case 'trial_needs_inbound':
      // The trial is dormant: wait for trial.reactivated before the next send.
      console.error('The prospect must reply before the next send.')
      break
    case 'trial_scope_violation':
      console.error('line_id is not the pool line of the trial, or to is not the paired handle.')
      break
    case 'unauthorized':
      console.error('The trial is revoked: its key no longer works.')
      break
    default:
      throw err
  }
}

import os
import time
import uuid

import requests

# One key per message, unique across all your trials.
idempotency_key = str(uuid.uuid4())  # Store it with your record of the message: reuse it to retry.

response = None
for attempt in range(3):
    if attempt > 0:
        time.sleep(2**attempt)
    try:
        response = requests.post(
            "https://api.isnap.ai/v1/messages",
            headers={
                "Authorization": f"Bearer {os.environ['ISNAP_TRIAL_KEY']}",
                "Idempotency-Key": idempotency_key,
            },
            json={
                "line_id": "line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd",  # pool_line_id of the trial
                "to": "+14155550123",  # paired_handle of the trial
                "body": "Thanks for trying this out. Reply to this message to continue.",
            },
            timeout=30,
        )
    except (requests.ConnectionError, requests.Timeout):
        # No response: the same key makes the retry safe.
        response = None
        continue
    if response.status_code not in (500, 503):
        break
    # 500 or 503: the same key makes the retry safe.

if response is None:
    raise SystemExit("No response. Retry later with the same key and the same body.")
payload = response.json()

if response.status_code == 202:
    print(payload["data"]["id"], payload["data"]["status"])
elif payload["error"]["code"] == "trial_needs_inbound":
    # The trial is dormant: wait for trial.reactivated before the next send.
    print("The prospect must reply before the next send.")
elif payload["error"]["code"] == "trial_scope_violation":
    print("line_id is not the pool line of the trial, or to is not the paired handle.")
elif payload["error"]["code"] == "unauthorized":
    print("The trial is revoked: its key no longer works.")
else:
    response.raise_for_status()

curl -sS -X POST "https://api.isnap.ai/v1/trial/trl_4Hn8Rz2Wq6Lb9Tc3Yx7Kd5Mv1/revoke" \
  -H "Authorization: Bearer $ISNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"rebind"}'

import { APIError, ISnapClient } from '@isnap/sdk'

const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY ?? '', maxRetries: 2 })

try {
  const result = await client.trial.revoke('trl_4Hn8Rz2Wq6Lb9Tc3Yx7Kd5Mv1', { reason: 'rebind' })
  console.log(result.status, result.already_revoked, result.reason)
} catch (err) {
  if (err instanceof APIError && err.code === 'rebind_cap_reached') {
    console.error(`Rebind limit reached. Retry in ${err.retryAfter} seconds.`)
  } else if (err instanceof APIError && err.code === 'rebind_not_allowed') {
    console.error('Rebind is turned off for this account. Revoke without a reason.')
  } else if (err instanceof APIError && err.code === 'trial_not_found') {
    console.error('Unknown trial id, or a trial of another account.')
  } else {
    throw err
  }
}

import os

import requests

response = requests.post(
    "https://api.isnap.ai/v1/trial/trl_4Hn8Rz2Wq6Lb9Tc3Yx7Kd5Mv1/revoke",
    headers={"Authorization": f"Bearer {os.environ['ISNAP_API_KEY']}"},
    json={"reason": "rebind"},
    timeout=30,
)
payload = response.json()

if response.status_code == 200:
    result = payload["data"]
    print(result["status"], result["already_revoked"], result["reason"])
elif payload["error"]["code"] == "rebind_cap_reached":
    print("Rebind limit reached. Retry at", payload["error"]["retry_at"])
elif payload["error"]["code"] == "rebind_not_allowed":
    print("Rebind is turned off for this account. Revoke without a reason.")
elif payload["error"]["code"] == "trial_not_found":
    print("Unknown trial id, or a trial of another account.")
else:
    response.raise_for_status()

curl -sS "https://api.isnap.ai/v1/trial/activity" \
  -H "Authorization: Bearer $ISNAP_TRIAL_KEY"

import { ISnapClient } from '@isnap/sdk'

const trialClient = new ISnapClient({ apiKey: process.env.ISNAP_TRIAL_KEY ?? '', maxRetries: 2 })

const activity = await trialClient.trial.activity()
console.log(activity.status, activity.activity_rule.remaining_before_dormant)

import os

import requests

response = requests.get(
    "https://api.isnap.ai/v1/trial/activity",
    headers={"Authorization": f"Bearer {os.environ['ISNAP_TRIAL_KEY']}"},
    timeout=30,
)
response.raise_for_status()
activity = response.json()["data"]
print(activity["status"], activity["activity_rule"]["remaining_before_dormant"])