Gateways

Gateways integrate your public IM identities, social network identities, and SMS with a queue. Gateways come online and go offline based on the presence or absence of operators assigned to the queue to which the gateway is connected.

Supported gateways: AIM

Using gateways, multiple operators can monitor your IM accounts without disconnecting each other. Plus guests can be transferred between operators as with regular web chats. And your gateway'd accounts' appearance to your guests will not change when using gateways. For example, your AIM account will still show up in their buddy list.

Authentication

LibraryH3lp supports cookie-based authentication. To learn more, you can read the details on authentication.

HTTP and HTTPS

Requests are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

URI

/2011-12-03/queues/{QueueId}/gateways

Resource properties

A gateway resource is represented by the following properties:

Property Description
id Unique integer identifier for a gateway.
queue The name of the queue to which the gateway is attached.
protocolId Unique integer identifier for a gateway's protocol.
protocol Descriptive string for a gateway's protocol. Possible values are: "aim", "twilio" (SMS)
username Username used to log into the gateway'd account. IM network usernames require a domain. Examples: username@aol.com
password Password used to log into the gateway'd account.

HTTP GET

Retrieve a list of gateways attached to the specified queue.

Response

Returns a JSON response containing a list of Gateway resources.

Example

GET /2011-12-03/queues/{QueueId}/gateways

[
  {
    "id": 8724,
    "queue": "example_queue",
    "protocolId": 14,
    "protocol": "twilio",
    "username": "+15555551234",
    "password": "smssms"
  }
]

HTTP POST

Allows you to add a new gateway to a queue. Each account that you add as a gateway can be attached to one and only one queue.

If the queue is online when you add a gateway, you will need to toggle the online/offline status of the queue in order for the gateway'd account to appear online. An easy way to do this is to temporarily unassign any online operators from the queue and then reassign them.

Once you have added a gateway, your operators should no longer sign into the external account associated with the gateway (e.g. AIM). Otherwise, the gateway will not function properly.

Required POST data

You must include, as JSON POST data, the following properties.

Property Description
username Username used to log into the account. IM network usernames require a domain. Examples: username@aol.com
password Password string used to log into the account.
protocol A string indicating the protocol for the gateway. Possible values are: "aim"

Response

If successful, returns a JSON response containing the resource representation of the newly created gateway. If unsuccessful, returns a JSON response with the following properties:

Property Description
success Boolean indicating if the request was successful.
message Optional. If success is null, message is a string describing the reason for the failed request.

Example

POST /2011-12-03/queues/9347/gateways
{
  "username": "myusername@aol.com"
  "password": "mysecretpassword"
  "protocol": "aim"
}

[
  {
    "id": 5915,
    "queue": "example-queue",
    "protocolId": 1,
    "protocol": "aim",
    "username": "myusername@aol.com",
    "password": "mysecretpassword"
  }
]

HTTP PUT

Not supported.

HTTP DELETE

Removes a gateway associated with a queue. For DELETE, you need to include protocol id and username as part of the URI as shown below. DELETE /2011-12-03/queues/{QueueId}/gateways/{ProtocolName}/{Username}

Do not remove gateways from a queue while the queue is online. Take the queue offline first. Otherwise your gateway'd account will be stuck in an online state.

Response

Returns a JSON response with the following properties:

Property Description
success Boolean indicating if the request was successful.
message Optional. If success is null, message is a string describing the reason for the failed request.

Example

DELETE /2011-12-03/queues/9347/gateways/aim/myusername@aol.com Note: DELETE URL decoded above for clarity.

{
  "success": true
}