API Basics

Allowed Methods

The Web1on1 API uses standard GET, POST, PATCH, and DELETE methods to modify endpoints.

PATCH behavior

Partial updates are implemented using PATCH, we do not support PUT for this.

When updating a resource object, a PATCH request will

• merge with the top-level resource object;
• replace any nested objects and arrays in your request body, not merge it.

As an example, given the record:

{
    "id": "591a3932dd2ec870ce85bd2f",
    "organization": "590bcf50458b716046347f36",
    "name": "Acme SmartSupp",
    "type": "smartsupp",
    "params": {
        "jid": "uid3710@s1.smartsupp.com",
        "password": "z3kR3t",
        "host": "s1.smartsupp.com",
        "port": 5223
    }
}

... the following PATCH request:

Request: PATCH /v2/services/591a3932dd2ec870ce85bd2f

{
    "name": "Acme Web Widget",
    "params": {
        "jid": "uid8965@s1.smartsupp.com",
        "password": "t0pN0tCH",
        "host": "s1.smartsupp.com"
    }
}

... will result in the following updated resource:

Response: 200 OK

{
    "id": "591a3932dd2ec870ce85bd2f",
    "organization": "590bcf50458b716046347f36",
    "name": "Acme Web Widget",
    "type": "smartsupp",
    "params": {
        "jid": "uid8965@s1.smartsupp.com",
        "password": "z3kR3t",
        "host": "s1.smartsupp.com",
        "port": 5222
    }
}

As you can see, the params nested object is replaced (with port set to the default 5222), the name was updated and the top-level type and organization were merged in from the original.

Filters, paginations and expansions

The API supports features for filtering and population of records. For example, to retrieve a Conversation with all Messages fully expanded, just add ?populate=messages to your GET request.

For a full overview of pagination, filtering and population capabilities, see 3.Fetching Resources.

3# Datetime Handling

All datetime objects in Web1on1 use ISO 8601 formatting. For datetime objects without a specified offset, UTC (Coordinated Universal Time) is assumed.

Rate Limiting

Web1on1's API limits each IP address and each API key to 20 requests per second. Exceeding this limit will result in a 429 - Too Many Requests error. If you require a higher limit, please contact support.

In addition to this basic request limit (applied per API key to all requests), two specialized rate limits are in place when creating messages (POST /v2/messages), as a bot user. These message creation limits are designed to limit the impact of bots getting stuck in a perpetual loop, either by itself or when interacting with other bots. The following limits apply per bot, per conversation:

• Bots can create a maximum of 8 identical messages in a single conversation within a 3-minute timespan.
• Bots can create a maximum of 20 consecutive messages in a single conversation per hour, after which bot messages within that hour are blocked until either an agent or a consumer replies in the conversation (thereby resetting the rate counter to 0).

For example, the following (pseudocode) examples would hit the identical or consecutive ratelimit on their last request:

for (0..9)
    POST /messages { text: "I've said this before..." }

for (0..21)
    POST /messages { text: **/set someVar ${Math.random()}** }

In both cases, Web1on1 will detect the perpetual loop and then prevent the bot from further flooding the conversation (within the rate-limited timespan). When designing, testing and monitoring bot conversation flows, you should detect rate limit errors and adjust the conversation design to stay within these limits; for example by combining multiple commands (/set, /assign, etc) into a single message.

Errors

Web1on1 uses standard HTTP status codes to communicate errors. The response body is JSON-encoded, and may include a "message" key with further information about the failure.

Common codes used by our API include:

Backward compatibility and API updates

While we won’t introduce any breaking changes, we plan on adding new features and new endpoints over time. This is a list of changes we consider to be backwards compatible:

• Adding new fields or links to the responses
• Adding new resources or endpoints
• Adding new (optional) request parameters
• Changing default page length for paginated resources

Please consider this when programming against the API and try to make sure these non-breaking changes don’t break your code. We recommend using our Node.js SDK for optimal, worry-free API usage.

If we introduce a breaking change, we will create new endpoints with a new version prefix in the URI.