> ## Documentation Index > Fetch the complete documentation index at: https://developers.bspk.com/llms.txt > Use this file to discover all available pages before exploring further. # List Messages > List messages ## OpenAPI ````yaml get /api/extraction/v1/messages openapi: 3.0.3 info: title: EXTRACTION API V1 version: 1.0.0 contact: name: BSPK API Support email: bspk-support@bspk.com description: >- # Introduction The BSPK RESTful JSON API gives you access to your company's BSPK data. For all BSPK API related questions please email: *bspk-support@bspk.com* ### Authentication BSPK uses Token-Based API Authentication. API keys can be managed from the API Keys section in your admin interface. All unauthenticated requests will return an HTTP 401 response. **Important:** Developers with BSPK API keys will be granted full access to the data in each endpoint. Access to this data is binary: everything or nothing. **Authorization header** Your `Authorization` header should be in the following format: ``` Authorization: Bearer [API_KEY] ``` ### Filter params `client_ids`: Accept multiple ids in a comma separated way, eg.: `client_ids=CLI1,CLI2` and can't be combined with `sales_associate_ids` filter param. Example: To filter messages by Sales Associates CL1 and CL2 you should do `https://api.bspk.com/api/extraction/v1/messages?client_ids=CLI1,CLI2`. `sales_associate_ids`: Accept multiple ids in a comma separated way, eg.: `sales_associate_ids=SA1,SA2` and can't be combined with `client_ids` filter param. Example: To filter messages by Sales Associates SA1 and SA2 you should do `https://api.bspk.com/api/extraction/v1/messages?sales_associate_ids=SA1,SA2`. `from`: Accepts date-time value (YYYY-MM-DDTHH:MM:SS) to filter records created after the specified value (boundaries included). Example: To filter messages by a Sales Associate from July 16, 2020 till the present date you should do `https://api.bspk.com/api/extraction/v1/messages?sales_associate_ids=SA1&from=2020-07-16T00:00:00`. `to`: Accepts date-time value (YYYY-MM-DDTHH:MM:SS) to filter records created before the specified value (boundaries included). Example: To filter messages by a Sales Associate since the begining till July 16, 2020 (inclusive) you should do `https://api.bspk.com/api/extraction/v1/messages?sales_associate_ids=SA1&from=2020-07-16T23:59:59`. `page`: Accepts a page number to filter records, defaults to `1`. Example: To return the second page of messages created you should do `https://api.bspk.com/api/v1/messages?page=2`. `per_page`: Accepts a number of records per page to filter records, defaults to `100` (maximum of `1000`). Example: To return the `30` messages per page you should do `https://api.bspk.com/api/extraction/v1/messages?per_page=30`. ### Pagination information We basically expose the pagination information all via header attributes, as follows: - Information about the total records the query will return in total (all pages) you can find the attribute `x-total-count` in the header. - Information about pagination is provided in the [Link header](https://datatracker.ietf.org/doc/html/rfc5988) of an API call. For example, let's make a curl request to the messages API, to find out how many message we have for the client CLI1: `$ curl -I "https://api.bspk.com/api/extraction/v1/messages?client_ids=CLI1"` The `-I` parameter indicates that we only care about the headers, not the actual content. In examining the result, you'll notice some information in the Link header that looks like this: ``` Link: ; rel="next", ; rel="last" ``` Since by default, all paginated queries start at page 1. rel="last" provides some more information, stating that the last page of results is on page 30. Thus, we have 29 more pages of information about messages from client CLI1 that we can consume. Always rely on these link relations provided to you. Don't try to guess or construct your own URL. ### Throttling API requests are limited to the amount specified in the returned `X-RateLimit-Limit` header (per 10 seconds). Exceeding that limit will cause BSPK to return an `HTTP 429` response. Check the `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers to see how many more requests you are allowed until throttling kicks in. ### Error Codes - 400 - Bad Request. - 401 - Unauthorized – Invalid BSPK API key. - 404 - Not Found – Resource not found. - 422 - Unprocessable entity. - 429 - Throttle Limit reached. - 500 - BSPK Internal Server Error ### Validation Methods that take input will validate all parameters. Any parameter that fails validation will trigger an error response with status HTTP 422. The response body will be a JSON object like the example below which includes a list of fields that failed validation. `{'errors':[{'title': 'No clients found with IDs: [NON_EXISTING_ID, OTHER_NON_EXISTING_ID]','code':'not_found'}]}` ### Additional Information - Fields without a value will return null - Timestamps are rendered in ISO-8601 format (e.g. 2018-07-21T17:32:28Z) - BSPK reserves the right to add more properties to objects, but will never change or remove them. Any breaking changes will result in a major API version update. servers: - url: https://api.bspk.com description: Production security: - BearerAuth: [] paths: /api/extraction/v1/messages: get: tags: - Messages summary: List Messages description: List messages operationId: listMessages parameters: - name: client_ids in: query required: false description: Client id owned by the brand schema: type: string - name: sales_associate_ids in: query required: false description: Sales Associate id owned by the brand schema: type: string - name: from in: query required: false description: >- Only show messages updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. schema: type: string - name: to in: query required: false description: >- Combined with the `from` parameter, only show messages updated whitin the given range (from..to) time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. schema: type: string - name: page in: query required: false description: 'Page number of the results to fetch. Default: 1' schema: type: string - name: per_page in: query required: false description: 'Results per page (max 100). Default: 30' schema: type: string responses: '200': description: Successful response, returns array of messages content: application/json: example: [] schema: $ref: '#/components/schemas/message' security: - BearerAuth: [] components: schemas: message: type: array items: type: object description: >- Get details about all messages sent by sales associates via Chat, Apple Messages, WhatsApp, WeChat or Line properties: store_id: type: string description: >- Unique identifier of the store where the message was created (based on associate assignment) store_name: type: string nullable: true description: >- Store name of where the message was created (based on associate assignment) sales_associate_id: type: string description: Unique identifier of the associate that created the message sales_associate_name: type: string description: Full name of the associate who created the message client_id: type: string description: Unique identifier of the client that the message is to client_name: type: string description: Full name of the client that the message is to body: type: string nullable: true description: The text included in the message channel: type: string description: The channel in which the message was sent from template_id: type: string nullable: true description: Unique identifier of the template that was used for the message template_name: type: string nullable: true description: Name of the template that was used for the message slice_id: type: integer nullable: true description: >- Unique identifier of the Slice that was include in the email (if any) media: type: array items: type: object properties: content_type: type: string description: The mime type of the media url: type: string description: >- The url of the images, videos or collection items included in the message size: type: string description: The size in KBs of the media required: - content_type - url - size created_at: type: string format: date_time description: Timestamp of when the message was created required: - store_id - store_name - sales_associate_id - sales_associate_name - client_id - slice_id - client_name - body - channel - template_id - template_name - media - created_at securitySchemes: BearerAuth: type: http scheme: bearer ````