Back to top

Token Chat Service

Chat allows for the sending of messages, encrypted with Signal protocol, between individuals. This can be messages relayed between users, or between an app and a user. Messages are sent via the Signal service.

Accounts

Account Creation

Create Account
PUT/v1/accounts/

Creates an account from account attributes, and when combined with the signature, ethereum address via ECDSA key recovery.

A guide to generating the Token-* headers can be found here

Example URI

PUT https://chat.service.tokenbrowser.com/v1/accounts/
Request
HideShow
Headers
Authorization: 
X-Signal-Agent:
Token-Timestamp:
Token-Signature:
Token-ID-Address:
Content-Type: application/json
Body
{
  "signalingKey": "...",
  "fetchesMessages": true,
  "registrationId": 1049,
  "name": null,
  "voice": false
}

Bootstrapped Account Creation

Create Account from bootstrap payload
PUT/v1/accounts/bootstrap/

Creates an account and provisions it with prekeys.

Example URI

PUT https://chat.service.tokenbrowser.com/v1/accounts/bootstrap/
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "identityKey": "BY10yMjz6aXkFkgimjLbBoP\/NvyrppofUmTrMqhuGPAR",
    "lastResortKey": {
      "keyId": uniqueInteger,
      "publicKey": "publicKeyOfLastResortKey"
    },
    "password": "password",
    "preKeys": [
      {
        "keyId": uniqueInteger,
        "publicKey": "publicKeyOfThisPreKey"
      },
      (...)
    ],
    "registrationId": integer,
    "signalingKey": "Random52ByteString",
    "signedPreKey": {
      "keyId": uniqueId,
      "publicKey": "signedPreKeyPublicKey",
      "signature": "signedPreKeySignature"
    }
}
Response  204
HideShow
Headers
Content-Type: application/json

Get server timestamp for bootstrap request
GET/v1/accounts/bootstrap/

Use this value to predict the correct timestamp to use when sending a PUT /v1/accounts/bootstrap/ request, to avoid erroneous rejection due to clock desync between client and server.

Example URI

GET https://chat.service.tokenbrowser.com/v1/accounts/bootstrap/
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "timestamp": 1481792827
}

Account Attributes

Set attributes on account
PUT/v1/accounts/attributes

Example URI

PUT https://chat.service.tokenbrowser.com/v1/accounts/attributes
Request
HideShow
Headers
Content-Type: application/json
Authorization:
X-Signal-Agent:
Body
{}
Schema
{
  "type": "object",
  "properties": {
    "signalingKey": {
      "type": "string"
    },
    "fetchesMessages": {
      "type": "boolean",
      "default": false
    },
    "registrationId": {
      "type": "integer",
      "format": "int32"
    },
    "name": {
      "type": "string"
    },
    "voice": {
      "type": "boolean",
      "default": false
    }
  }
}

Messaging

Message

Send message
PUT/v1/messages/{destination}

Example URI

PUT https://chat.service.tokenbrowser.com/v1/messages/destination
URI Parameters
HideShow
destination
string (required) 

Ethereum address of message recipient

Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Authorization:
Body
{
  "messages": [
    {
      "timestamp": 17884000,
      "destinationRegistrationId": 39167258,
      "content": "irure aliquip minim sed",
      "body": "aliquip ea",
      "destinationDeviceId": -14766533,
      "relay": "est",
      "destination": "dolore ut dolor sunt",
      "type": -15267097
    },
    {
      "content": "laborum",
      "timestamp": -35314861,
      "relay": "Lorem amet",
      "destinationRegistrationId": 68353787,
      "destinationDeviceId": 75332158,
      "destination": "ut dolore"
    }
  ]
}
Schema
{
  "type": "object",
  "required": [
    "messages"
  ],
  "properties": {
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "integer",
            "format": "int32"
          },
          "destination": {
            "type": "string"
          },
          "destinationDeviceId": {
            "type": "integer",
            "format": "int64"
          },
          "destinationRegistrationId": {
            "type": "integer",
            "format": "int32"
          },
          "body": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "relay": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          }
        }
      }
    },
    "relay": {
      "type": "string"
    },
    "timestamp": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{}
Schema
{
  "type": "object",
  "properties": {
    "needsSync": {
      "type": "boolean",
      "default": false
    }
  }
}

Pending Messages Collection

Get pending messages
GET/v1/messages

Example URI

GET https://chat.service.tokenbrowser.com/v1/messages
Request
HideShow
Headers
Accept: application/json
Authorization:
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Schema
{
  "type": "object",
  "properties": {
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "integer",
            "format": "int32"
          },
          "relay": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          },
          "source": {
            "type": "string"
          },
          "sourceDevice": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "byte"
            }
          },
          "content": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "byte"
            }
          }
        }
      }
    },
    "more": {
      "type": "boolean",
      "default": false
    }
  }
}

Pending Message

Delete pending message
DELETE/v1/messages/{source}/{timestamp}

Example URI

DELETE https://chat.service.tokenbrowser.com/v1/messages/source/timestamp
URI Parameters
HideShow
source
string (required) 

Ethereum address of sender

timestamp
number (required) 

timestamp of pending message

Delivery Receipt

Send delivery receipt
PUT/v1/receipt/{destination}/{message_id}

Example URI

PUT https://chat.service.tokenbrowser.com/v1/receipt/destination/message_id
URI Parameters
HideShow
destination
string (required) 

Ethereum address of message recipient

message_id
number (required) 

ID of message

Attachments Collection

Allocate attachment
GET/v1/attachments

Example URI

GET https://chat.service.tokenbrowser.com/v1/attachments
Request
HideShow
Headers
Accept: application/json
Authorization:
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "location": {
      "type": "string"
    }
  }
}

Attachment

Redirect To Attachment
GET/v1/attachments/{attachment_id}

Example URI

GET https://chat.service.tokenbrowser.com/v1/attachments/attachment_id
URI Parameters
HideShow
attachment_id
number (required) 

ID of attachment

attachmentId
string (required) 
relay
string (required) 
Request
HideShow
Headers
Accept: application/json
Authorization:
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{
  "location": "do in"
}
Schema
{
  "type": "object",
  "properties": {
    "location": {
      "type": "string"
    }
  }
}

Push Notifications

APN Push Service Registration

Apple Push Notification Service

Set APN registration id
PUT/v1/accounts/apn/

Example URI

PUT https://chat.service.tokenbrowser.com/v1/accounts/apn/
Request
HideShow
Headers
Content-Type: application/json
Authorization:
Body
{
  "apnRegistrationId": "in quis"
}
Schema
{
  "type": "object",
  "properties": {
    "apnRegistrationId": {
      "type": "string"
    },
    "voipRegistrationId": {
      "type": "string"
    }
  }
}

Delete APN registration id
DELETE/v1/accounts/apn/

Example URI

DELETE https://chat.service.tokenbrowser.com/v1/accounts/apn/

GCM Push Service Registration

Google Cloud Messaging

Set GCM registration id
PUT/v1/accounts/gcm/

Example URI

PUT https://chat.service.tokenbrowser.com/v1/accounts/gcm/
Request
HideShow
Headers
Content-Type: application/json
Authorization:
Body
{
  "webSocketChannel": false
}
Schema
{
  "type": "object",
  "properties": {
    "gcmRegistrationId": {
      "type": "string"
    },
    "webSocketChannel": {
      "type": "boolean",
      "default": false
    }
  }
}

Delete GCM registration id
DELETE/v1/accounts/gcm/

Example URI

DELETE https://chat.service.tokenbrowser.com/v1/accounts/gcm/

Devices

Devices Collection

Get list of devices
GET/v1/devices/

Example URI

GET https://chat.service.tokenbrowser.com/v1/devices/

Device

Delete device from account
DELETE/v1/devices/{device_id}

Example URI

DELETE https://chat.service.tokenbrowser.com/v1/devices/device_id
URI Parameters
HideShow
device_id
number (required) 

ID of the device

Keys

Keys Collection

Get count of PreKeys
GET/v2/keys

Example URI

GET https://chat.service.tokenbrowser.com/v2/keys
Request
HideShow
Headers
Accept: application/json
Authorization:
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{}
Schema
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "format": "int32"
    }
  }
}

Set keys
PUT/v2/keys

Example URI

PUT https://chat.service.tokenbrowser.com/v2/keys
Request
HideShow
Headers
Content-Type: application/json
Authorization:
Body
{
  "lastResortKey": {
    "keyId": -28579668
  },
  "preKeys": [
    {
      "keyId": -81338653
    },
    {
      "keyId": -26773841
    },
    {
      "keyId": -9396493
    },
    {
      "keyId": 15463664,
      "publicKey": "elit"
    },
    {
      "keyId": -98227863
    }
  ],
  "signedPreKey": {
    "keyId": -77033897
  }
}
Schema
{
  "type": "object",
  "required": [
    "lastResortKey",
    "preKeys",
    "signedPreKey"
  ],
  "properties": {
    "preKeys": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "keyId"
        ],
        "properties": {
          "keyId": {
            "type": "integer",
            "format": "int64"
          },
          "publicKey": {
            "type": "string"
          }
        }
      }
    },
    "signedPreKey": {
      "type": "object",
      "required": [
        "keyId"
      ],
      "properties": {
        "keyId": {
          "type": "integer",
          "format": "int64"
        },
        "publicKey": {
          "type": "string"
        },
        "signature": {
          "type": "string"
        }
      }
    },
    "lastResortKey": {
      "type": "object",
      "required": [
        "keyId"
      ],
      "properties": {
        "keyId": {
          "type": "integer",
          "format": "int64"
        },
        "publicKey": {
          "type": "string"
        }
      }
    },
    "identityKey": {
      "type": "string"
    }
  }
}

Signed Key

Get signed key
GET/v2/keys/signed

Example URI

GET https://chat.service.tokenbrowser.com/v2/keys/signed
Request
HideShow
Headers
Accept: application/json
Authorization:
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{
  "keyId": 52662686
}
Schema
{
  "type": "object",
  "required": [
    "keyId"
  ],
  "properties": {
    "keyId": {
      "type": "integer",
      "format": "int64"
    },
    "publicKey": {
      "type": "string"
    },
    "signature": {
      "type": "string"
    }
  }
}

Set signed key
PUT/v2/keys/signed

Example URI

PUT https://chat.service.tokenbrowser.com/v2/keys/signed
Request
HideShow
Headers
Content-Type: application/json
Authorization:
Body
{
  "keyId": -4546692,
  "signature": "cupidatat"
}
Schema
{
  "type": "object",
  "required": [
    "keyId"
  ],
  "properties": {
    "keyId": {
      "type": "integer",
      "format": "int64"
    },
    "publicKey": {
      "type": "string"
    },
    "signature": {
      "type": "string"
    }
  }
}

PreKeyBundle

Get bundle for any user
GET/v2/keys/{eth_address}/{device_id}

Example URI

GET https://chat.service.tokenbrowser.com/v2/keys/eth_address/device_id
URI Parameters
HideShow
eth_address
string (required) 

Ethereum address of message recipient

device_id
number (required) 

ID of device. Wildcard ‘*’ can (and should) be used in place of targeting a specific device in most cases.

Request
HideShow
Headers
Accept: application/json
Authorization:
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{}
Schema
{
  "type": "object"
}

Generated by aglio on 02 Oct 2017