Working Hours & Scheduling

​

How it works

• POST /v1/messages accepts the send straight away (202 Accepted) with status: "pending", whatever the time.
• If the recipient’s local time is inside your working window, the message goes out within seconds.
• If it is outside, the message stays pending and goes out automatically when the window next opens. There is no separate status or webhook for this wait; a message.sent webhook fires when it goes out.

​

Configuring working hours

​

Per-contact timezone

1. Explicit override — if you set the timezone field on the contact (via POST /v1/contacts or the dashboard).
2. Area-code inference — for North American numbers, iBubbl infers a default timezone from the area code (e.g., +1415... → America/Los_Angeles).
3. Account timezone — the timezone in your dashboard’s Settings → Notifications, which starts as your browser’s timezone.
4. America/New_York — if none of the above is set.

curl -X POST https://api.ibubbl.com/v1/contacts \
  -H "Authorization: Bearer $IBUBBL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "timezone": "America/New_York"
  }'

const res = await fetch("https://api.ibubbl.com/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.IBUBBL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "+14155551234",
    timezone: "America/New_York",
  }),
  signal: AbortSignal.timeout(10_000),
});

const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
console.log(data.id, data.timezone);

import os

import requests

API_KEY = os.environ["IBUBBL_API_KEY"]

res = requests.post(
    "https://api.ibubbl.com/v1/contacts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "phone": "+14155551234",
        "timezone": "America/New_York",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
print(data["id"], data["timezone"])

​

Detecting a held send

{
  "id": "4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d",
  "status": "pending",
  "to": "+14155551234",
  "held_reason": "working_hours",
  "held_until": "2026-10-08T16:00:00+00:00"
}

• held_reason — why it is waiting right now: working_hours (outside the contact’s working hours) or hourly_limit (your line has messaged 30 new contacts in the last 60 minutes; the message stays pending and goes out by itself when a slot frees — see Limits and queues).
• held_until — when it is expected to go out. For working_hours, the contact’s next opening: it is recomputed within about 10 seconds when your hours change, and it is null if no sending day is enabled. For hourly_limit, an estimate of when a slot frees, or null if there is none.

​

Capacity holds (status: "queued")