Skip to the page

API reference

Change the sending rules

Changes the settings you send; the rest stay.

PATCH/v1/settings

Changes the settings you send; the rest stay. Texts already waiting are held, or freed, under the new rules within a minute. texting_hours.all sets every place at once and null puts every place back to its law; texting_hours.places sets one place each, and null hours put a place back to its law. paused_until pauses all sending until a time, and null resumes it. stop_words.words replaces the stop words with your own list; null goes back to the defaults.

Needs a key with the messages:send scope. Keys and scopes

Request body

  • business_namestring or null

    Your business’s name, as {{business}} fills it in. Null clears it.

    Up to 120 characters.

  • time_zonestring

    An IANA zone, such as America/Chicago.

    Up to 64 characters.

  • pace_secondsinteger

    5 to 300.

  • new_people_per_dayinteger

    0 to 1,000.

  • texting_hoursobject

    Change texting hours for every place, some places, or both.

    Show its 3 fields
    • allobject or null

      Hours for every place at once. Each place gets the narrower of these hours and its law, unless allow_wider is true. Null puts every place back to its law. Applied before places.

      Show its 3 fields
      • start_hourintegerrequired

        The first hour a text may go where the person lives, 0 to 23.

        0 to 23.

      • end_hourintegerrequired

        The hour texts stop, 1 to 24. 24 is midnight.

        1 to 24.

      • sundaysbooleanrequired

        Whether texts may go on Sunday.

    • allow_widerboolean

      With all: true sets every place to those hours as sent, even where they’re wider than the place’s law. Left out or false, no place goes past its law. places are always set as sent.

    • placesarray of object

      Hours for one place each, applied in order. Hours equal to a place’s law are stored as no change.

      Up to 57 items.

      Show its 2 fields
      • placestringrequired

        A state, DC or territory by its two-letter code, or OTHER for people with no known state (group chats, email addresses and numbers from outside the US), whose hours are read in time_zone.

        One of AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY, DC, PR, VI, GU, MP, AS, OTHER.

      • hoursobject or nullrequired

        The place’s hours. Null puts it back to its law.

        Show its 3 fields
        • start_hourintegerrequired

          The first hour a text may go where the person lives, 0 to 23.

          0 to 23.

        • end_hourintegerrequired

          The hour texts stop, 1 to 24. 24 is midnight.

          1 to 24.

        • sundaysbooleanrequired

          Whether texts may go on Sunday.

  • stop_wordsobject
    Show its 2 fields
    • enabledboolean
    • wordsarray of strings or null

      Your own stop words, matched without case against a whole reply. Null goes back to the defaults.

      Up to 50 items.

  • expiry_hoursinteger

    1 to 168.

  • inbound_modestring

    One of replies, everything.

  • paused_untiltimestamp or null

    Pause sending until this time; null resumes.

Example

curl -X PATCH "https://getdogbot.com/api/v1/settings" \
  -H "Authorization: Bearer $DOGBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pace_seconds": 30,
    "texting_hours": {
      "places": [
        {
          "place": "FL",
          "hours": {
            "start_hour": 9,
            "end_hour": 18,
            "sundays": false
          }
        }
      ]
    }
  }'

Response

200: The settings after the change.

  • object"settings"required
  • business_namestring or nullrequired

    Your business’s name, which {{business}} fills in. Null until you set it; texts that would name the business leave it out until then.

  • time_zonestringrequired

    The zone daily limits are read in, and the texting hours of people with no known state.

  • pace_secondsintegerrequired

    Seconds between two texts leaving the Mac, 5 to 300.

  • new_people_per_dayintegerrequired

    How many people you have never texted with DogBot may be texted in a day, 0 to 1,000.

  • texting_hoursobjectrequired

    When texts may go where each person lives. Every place starts at its law: the state’s own rule where it has one, else the federal 8 AM to 9 PM. A text waits until it’s within the hours of the person’s state, from their contact’s state or else their area code.

    Show its 2 fields
    • customarray of objectrequired

      The places whose hours you changed, in the order of TEXTING_PLACES. Every other place follows its law.

      Show its 5 fields
      • placestringrequired

        A state, DC or territory by its two-letter code, or OTHER for people with no known state (group chats, email addresses and numbers from outside the US), whose hours are read in time_zone.

        One of AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY, DC, PR, VI, GU, MP, AS, OTHER.

      • start_hourintegerrequired

        The first hour a text may go where the person lives, 0 to 23.

        0 to 23.

      • end_hourintegerrequired

        The hour texts stop, 1 to 24. 24 is midnight.

        1 to 24.

      • sundaysbooleanrequired

        Whether texts may go on Sunday.

      • wider_than_lawbooleanrequired

        Whether these hours let a text go at an hour or on a day the place’s law doesn’t.

    • kept_at_lawarray of strings

      Only in the answer to a save of hours for every place: the places kept at, or put back to, their law because those hours share no hour with it. warnings says the same in words.

      One of AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY, DC, PR, VI, GU, MP, AS, OTHER.

  • stop_wordsobjectrequired
    Show its 4 fields
    • enabledbooleanrequired

      Whether a reply of only a stop word puts the person on the stop list.

    • wordsarray of stringsrequired

      The stop words: your own list, or the defaults when custom is false.

    • custombooleanrequired

      Whether you changed the list. False means DogBot’s defaults.

    • start_wordsarray of stringsrequired

      Words that take a person who stopped by reply off the list again.

  • expiry_hoursintegerrequired

    A text still waiting this long after it was due expires, 1 to 168.

  • inbound_modestringrequired

    Which chats the Mac copies to DogBot: replies (people DogBot has texted) or everything.

    One of replies, everything.

  • paused_untiltimestamp or nullrequired

    While you have sending paused, until when.

  • platform_daily_limitintegerrequired

    DogBot’s ceiling on texts a day, which you can’t change.

  • warningsarray of stringsrequired

    Things worth knowing about these settings, in words.

Response200
{
  "object": "settings",
  "business_name": "Dana Realty",
  "time_zone": "America/Chicago",
  "pace_seconds": 30,
  "new_people_per_day": 50,
  "texting_hours": {
    "custom": [
      {
        "place": "FL",
        "start_hour": 9,
        "end_hour": 18,
        "sundays": false,
        "wider_than_law": false
      }
    ]
  },
  "stop_words": {
    "enabled": true,
    "words": [
      "stop",
      "stopall",
      "unsubscribe",
      "cancel",
      "end",
      "quit"
    ],
    "custom": false,
    "start_words": [
      "start",
      "unstop",
      "yes"
    ]
  },
  "expiry_hours": 24,
  "inbound_mode": "replies",
  "paused_until": null,
  "platform_daily_limit": 1000,
  "warnings": []
}

Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

CodeStatusWhat it means
unauthorized401The request carried no key, or a key DogBot doesn’t know: mistyped, revoked, or a test key sent to the live API.
insufficient_scope403The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.
rate_limited429Too many requests. A key may make 120 requests a minute. The RateLimit header says how many are left, and Retry-After how long to wait.
internal500Something went wrong on DogBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.
invalid_request400Something in the request doesn’t fit: a missing or malformed field, a bad id, or a combination the endpoint refuses. details names each field.

Try it

Call this operation from the page with your own key. The key stays in this tab and is forgotten when you leave.