# 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](https://getdogbot.com/docs/concepts/api-keys)

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `business_name` | string or null | No | Your business’s name, as `{{business}}` fills it in. Null clears it. Up to 120 characters |
| `time_zone` | string | No | An IANA zone, such as `America/Chicago`. Up to 64 characters |
| `pace_seconds` | integer | No | 5 to 300 |
| `new_people_per_day` | integer | No | 0 to 1,000 |
| `texting_hours` | object | No | Change texting hours for every place, some places, or both. |
| `texting_hours.all` | object or null | No | 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`. |
| `texting_hours.all.start_hour` | integer | Yes | The first hour a text may go where the person lives, 0 to 23. 0 to 23 |
| `texting_hours.all.end_hour` | integer | Yes | The hour texts stop, 1 to 24. 24 is midnight. 1 to 24 |
| `texting_hours.all.sundays` | boolean | Yes | Whether texts may go on Sunday. |
| `texting_hours.allow_wider` | boolean | No | 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. |
| `texting_hours.places` | array of object | No | Hours for one place each, applied in order. Hours equal to a place’s law are stored as no change. Up to 57 items |
| `texting_hours.places[].place` | string | Yes | 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` |
| `texting_hours.places[].hours` | object or null | Yes | The place’s hours. Null puts it back to its law. |
| `texting_hours.places[].hours.start_hour` | integer | Yes | The first hour a text may go where the person lives, 0 to 23. 0 to 23 |
| `texting_hours.places[].hours.end_hour` | integer | Yes | The hour texts stop, 1 to 24. 24 is midnight. 1 to 24 |
| `texting_hours.places[].hours.sundays` | boolean | Yes | Whether texts may go on Sunday. |
| `stop_words` | object | No |   |
| `stop_words.enabled` | boolean | No |   |
| `stop_words.words` | array of strings or null | No | Your own stop words, matched without case against a whole reply. Null goes back to the defaults. Up to 50 items |
| `expiry_hours` | integer | No | 1 to 168 |
| `inbound_mode` | string | No | One of `replies`, `everything` |
| `paused_until` | timestamp or null | No | Pause sending until this time; null resumes. |

## Example

```bash
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
          }
        }
      ]
    }
  }'
```

```ts
import DogBot from '@getdogbot/sdk';

const client = new DogBot({ apiKey: process.env.DOGBOT_API_KEY });

const settings = await client.settings.update({
  paceSeconds: 30,
  textingHours: {
    places: [
      {
        place: 'FL',
        hours: {
          startHour: 9,
          endHour: 18,
          sundays: false,
        },
      },
    ],
  },
});
console.log(settings);
```

```python
import os
from dogbot import DogBot

client = DogBot(api_key=os.environ["DOGBOT_API_KEY"])

settings = client.settings.update(
    pace_seconds=30,
    texting_hours={
        "places": [
            {
                "place": "FL",
                "hours": {
                    "start_hour": 9,
                    "end_hour": 18,
                    "sundays": False,
                },
            },
        ],
    },
)
print(settings)
```

## Response

`200`: The settings after the change.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "settings" | Yes |   |
| `business_name` | string or null | Yes | 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_zone` | string | Yes | The zone daily limits are read in, and the texting hours of people with no known state. |
| `pace_seconds` | integer | Yes | Seconds between two texts leaving the Mac, 5 to 300. |
| `new_people_per_day` | integer | Yes | How many people you have never texted with DogBot may be texted in a day, 0 to 1,000. |
| `texting_hours` | object | Yes | 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. |
| `texting_hours.custom` | array of object | Yes | The places whose hours you changed, in the order of `TEXTING_PLACES`. Every other place follows its law. |
| `texting_hours.custom[].place` | string | Yes | 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` |
| `texting_hours.custom[].start_hour` | integer | Yes | The first hour a text may go where the person lives, 0 to 23. 0 to 23 |
| `texting_hours.custom[].end_hour` | integer | Yes | The hour texts stop, 1 to 24. 24 is midnight. 1 to 24 |
| `texting_hours.custom[].sundays` | boolean | Yes | Whether texts may go on Sunday. |
| `texting_hours.custom[].wider_than_law` | boolean | Yes | Whether these hours let a text go at an hour or on a day the place’s law doesn’t. |
| `texting_hours.kept_at_law` | array of strings | No | 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_words` | object | Yes |   |
| `stop_words.enabled` | boolean | Yes | Whether a reply of only a stop word puts the person on the stop list. |
| `stop_words.words` | array of strings | Yes | The stop words: your own list, or the defaults when `custom` is false. |
| `stop_words.custom` | boolean | Yes | Whether you changed the list. False means DogBot’s defaults. |
| `stop_words.start_words` | array of strings | Yes | Words that take a person who stopped by reply off the list again. |
| `expiry_hours` | integer | Yes | A text still waiting this long after it was due expires, 1 to 168. |
| `inbound_mode` | string | Yes | Which chats the Mac copies to DogBot: `replies` (people DogBot has texted) or `everything`. One of `replies`, `everything` |
| `paused_until` | timestamp or null | Yes | While you have sending paused, until when. |
| `platform_daily_limit` | integer | Yes | DogBot’s ceiling on texts a day, which you can’t change. |
| `warnings` | array of strings | Yes | Things worth knowing about these settings, in words. |

The answer, `200`:

```json
{
  "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.

| Code                                                    | Status | What it means                                                                                                                                    |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`unauthorized`](https://getdogbot.com/docs/errors/unauthorized)             | 401    | The request carried no key, or a key DogBot doesn’t know: mistyped, revoked, or a test key sent to the live API.                                 |
| [`insufficient_scope`](https://getdogbot.com/docs/errors/insufficient_scope) | 403    | The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.                                                   |
| [`rate_limited`](https://getdogbot.com/docs/errors/rate_limited)             | 429    | Too 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.      |
| [`internal`](https://getdogbot.com/docs/errors/internal)                     | 500    | Something went wrong on DogBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.                     |
| [`invalid_request`](https://getdogbot.com/docs/errors/invalid_request)       | 400    | Something 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
