Skip to main content
PATCH
Update the configuration of a line
  • Credential: an API key of the owner of the line. See Configuration for the direction rule, the ranges and the way back to a default.
  • Line-scoped keys: a line-scoped key gets 403 forbidden unless the line is in its list.
  • Idempotency-Key: not honored. The operation sets the keys you send and keeps the others, so the same request sent twice leaves the line in the same state.
  • Events: none. See What events do not announce.
  • Body: null is not accepted for any key, and an unknown key is refused. To remove an override, send the key with its default value. For activity_curve, send the default_activity_curve of GET /v1/lines/{id}/config: a curve that gives every hour the same weight as that curve, an hour with no entry counting as 0, removes the override. A request that does not send activity_curve leaves its override in place.

​
Errors

The errors that every operation shares are in Errors.

Authorizations

​
Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Path Parameters

​
id
string
required

Id of a line: line_ followed by 25 letters or digits.

Pattern: ^line_[0-9A-Za-z]{25}$

Body

application/json

The keys to override on this line. Send a key with its default value to remove its override. null and unknown keys return 400 validation_failed.

​
default_use_typing_indicator
boolean

Whether a message that does not state use_typing_indicator shows the typing indicator before it is sent.

​
quota_overflow_behavior
enum<string>

What happens to a send that reaches a sending limit. queue: the message is accepted and held, with status: scheduled. drop or fail: the send returns 429 and nothing is stored; the two values behave the same.

Available options:
queue,
drop,
fail
​
daily_new_contact_limit
integer

Distinct new contacts the line can message per rolling 24 hours. Accepted values: 5 to 200. Another integer from 1 to 500 returns 422 limit_out_of_bounds. A value outside 1 to 500, or one that is not an integer, returns 400 validation_failed. It can only be lowered below the default (403 cannot_increase_limit), except on a BYOD line, where it can be raised up to knobs.daily_new_contact_limit.max.

Required range: 1 <= x <= 500
​
daily_known_contact_limit
integer

Distinct known contacts the line can message per rolling 24 hours. Accepted values: 10 to 1,000. Another integer from 1 to 2,000 returns 422 limit_out_of_bounds. A value outside 1 to 2,000, or one that is not an integer, returns 400 validation_failed. It can only be lowered below the default (403 cannot_increase_limit), except on a BYOD line, where it can be raised up to knobs.daily_known_contact_limit.max.

Required range: 1 <= x <= 2000
​
daily_total_message_limit
integer

Messages the line can send per rolling 24 hours. Accepted values: 10 to 1,000. Another integer from 1 to 100,000 returns 422 limit_out_of_bounds. A value outside 1 to 100,000, or one that is not an integer, returns 400 validation_failed. It can only be lowered below the default (403 cannot_increase_limit), except on a BYOD line, where it can be raised up to knobs.daily_total_message_limit.max.

Required range: 1 <= x <= 100000
​
hourly_message_limit
integer

Messages the line can send per rolling 60 minutes. Accepted values: 5 to 200. Another integer from 1 to 1,000 returns 422 limit_out_of_bounds. A value outside 1 to 1,000, or one that is not an integer, returns 400 validation_failed. It can only be lowered below the default (403 cannot_increase_limit), except on a BYOD line, where it can be raised up to knobs.hourly_message_limit.max.

Required range: 1 <= x <= 1000
​
minute_message_limit
integer

Messages the line can send per rolling 60 seconds. Accepted values: 1 to 60. An integer from 61 to 100 returns 422 limit_out_of_bounds. A value outside 1 to 100, or one that is not an integer, returns 400 validation_failed. It can only be lowered below the default (403 cannot_increase_limit), except on a BYOD line, where it can be raised up to knobs.minute_message_limit.max.

Required range: 1 <= x <= 100
​
min_inter_message_seconds
integer

Minimum number of seconds between two messages of the line. Accepted values: 1 to 300. It can only be raised above the default (403 cannot_decrease_delay).

Required range: 1 <= x <= 300
​
min_inter_new_contact_seconds
integer

Minimum number of seconds between two first messages to new contacts. Accepted values: 30 to 3,600. It can only be raised above the default (403 cannot_decrease_delay).

Required range: 30 <= x <= 3600
​
max_queue_depth
integer

Maximum number of held messages on the line: beyond it, a send that would be held returns 429 queue_full. Accepted values: 10 to 5,000. It can only be lowered below the default (403 cannot_increase_limit).

Required range: 10 <= x <= 5000
​
reply_window_hours
integer

Reply lane: a message qualifies as a reply when its recipient messaged the line within this number of hours. Accepted values: 1 to 168. It can only be lowered below the default (403 cannot_increase_limit).

Required range: 1 <= x <= 168
​
reply_max_per_inbound
integer

Reply lane: the number of messages to a contact that qualify as replies after each message from that contact. 0 turns the reply lane off. Accepted values: 0 to 50. It can only be lowered below the default (403 cannot_increase_limit).

Required range: 0 <= x <= 50
​
daily_reply_limit
integer

Reply-lane allowance: the number of replies per rolling 24 hours that can pass a sending limit through the reply lane. 0 turns the reply lane off. Accepted values: 0 to 1,000. It can only be lowered below the default (403 cannot_increase_limit).

Required range: 0 <= x <= 1000
​
timezone
string

IANA time zone name of the line, for example America/New_York (400 validation_failed otherwise). iSnap reads quiet hours in it for a recipient whose own time zone it does not know. Once set, it can be replaced but not removed.

​
activity_curve
object[]

The sending hours of the line, as a list of hours with a weight. An hour with weight 0, or with no entry, is a quiet hour: a message accepted then is held until the next hour that has a weight. Messages held by a 24-hour sending limit are placed in the hours in proportion to their weights. It needs at least one entry, no hour twice, and a total weight above 0 (422 invalid_activity_curve otherwise). A curve the same as default_activity_curve (returned by GET /v1/lines/{id}/config) removes the override instead of setting one. Two curves are the same when every hour from 0 to 23 has the same weight in both, an hour with no entry counting as 0: the order of the entries does not matter, and a curve that lists only its weighted hours is the same as the 24-hour curve with 0 everywhere else.

Response

The configuration of the line after the change.

​
success
enum<boolean>
required

Always true on a success response.

Available options:
true
​
data
object
required

The sending configuration of a line.

​
trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

​
request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.