NAV Navbar
shell php

Introduction

Welcome to Colizey, the marketplace dedicated to sports.

This api contains documentation about Messenger exchanges.

API Usage

The full API usage is described on the main documentation

Messenger API

With the Messenger API, you can initiate a discussion with your customers or answer them.

Available subjects

In order to create a new thread, you must choose a subject beforehand among the available ones:

subjects
order
delivery
invoice_request
return_request
product_information
report_an_issue

Create a thread

curl "https://api.colizey.fr/merchant/messenger/message/addToOrder/{orderId}" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "subject=Lorem ipsum" \
  --data-urlencode "message=Lorem ipsum" \
  --data-urlencode "files=7b807de6-b6f2-4bc2-b338-8e90ce0b15c2,b674bed7-c355-4dab-8c05-8a1d0631a0e8"
  -X POST

Returns the id of the thread.

{"id": "25780e5b-035b-4fbe-a29d-e85eea0fd867"}

To initiate an exchange with a customer, you must create a thread related to an order.

First, you need to choose a subject among the available ones:

Then build the request with the following parameters:

parameters type required Description
subject string yes Subject of the thread (must be one of the available ones)
message string yes First message of the thread
files string no File UUIDs as a string, separated by a comma (,)

[ ℹ ] To attach a file, please refer to the file section

Add a message to a thread

curl "https://api.colizey.fr/merchant/messenger/message/addToThread/{threadId}" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "message=Lorem ipsum" \
  --data-urlencode "files=7b807de6-b6f2-4bc2-b338-8e90ce0b15c2,b674bed7-c355-4dab-8c05-8a1d0631a0e8" \
  -X POST

Example response

{
    "id": "1c63b3a0-3d39-4fee-b4e8-3f053a68b8d1",
    "message": "Lorem ipsum",
    "author": 1,
    "createdAt": "2022-05-23T14:34:19+00:00",
    "readAt": null,
    "files": []
}

Once a thread is created, you can add messages to it.

parameters type required Description
message string yes New message of the thread
files string no File UUIDs as a string, separated by a comma (,)

[ ℹ ] To attach a file, please refer to the file section

Get threads

curl "https://api.colizey.fr/merchant/messenger/threads" \
  -H "x-apikey: xxxxxxxxxxxxxx"

You can retrieve threads linked to you.

Here you can find various parameters to help you filter the results:

parameters in type required Description
orderId query uuid no Get threads from orderId
limit query integer no Limit the number of results
offset query integer no Starting offset
from query date-time no threads after this date
to query date-time no threads before this date
(removed) dateType query enum[create, update] no Filter by creation date or by last update
(removed) actionNeeded query boolean no To fetch only new messages
(removed) toProcess query boolean no To fetch only unprocessed messages
(removed) onlyUnanswered query boolean no To fetch only unanswered messages (the parameter toProcess will be ignored)
(new) status query integer no Fetch threads with a specific status
(new) locale query enum[fr, it] no Fetch threads according to the locale of the order (e.g. if the order was placed on colizey.fr, the locale will be fr)

Here the available statuses:

status description
(default) 0 All threads
1 Unanswered
3 Open threads
4 Archived

Example response

[
  {
    "order": {
      "id": "cc511c09-b792-4202-88e8-71c50e758d9e",
      "orderNumber": "XXX"
    },
    "user": {
      "firstName": "Firstname",
      "lastName": "Lastname"
    },
    "id": "0d82d3c4-653f-47ac-b4e9-31b9106ba73a",
    "subject": "order",
    "createdAt": "2022-05-23T14:30:34+00:00",
    "updatedAt": "2022-05-23T14:34:19+00:00",
    "author": 1,
    "actionMerchantNeeded": false,
    "closed": true,
    "messages": [
      {
        "id": "1c63b3a0-3d39-4fee-b4e8-3f053a68b8d1",
        "message": "Lorem Ipsum",
        "author": 1,
        "createdAt": "2022-05-23T14:34:19+00:00",
        "readAt": null,
        "files": []
      }
    ]
  }
]

Get thread

curl "https://api.colizey.fr/merchant/messenger/threads/{threadId}" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Example response

{
  "order": {
    "id": "cc511c09-b792-4202-88e8-71c50e758d9e",
    "orderNumber": "XXX"
  },
  "user": {
    "firstName": "Firstname",
    "lastName": "Lastname"
  },
  "id": "0d82d3c4-653f-47ac-b4e9-31b9106ba73a",
  "subject": "order",
  "createdAt": "2022-05-23T14:30:34+00:00",
  "updatedAt": "2022-05-23T14:34:19+00:00",
  "author": 1,
  "actionMerchantNeeded": false,
  "closed": true,
  "messages": [
    {
      "id": "1c63b3a0-3d39-4fee-b4e8-3f053a68b8d1",
      "message": "Lorem Ipsum",
      "author": 1,
      "createdAt": "2022-05-23T14:34:19+00:00",
      "readAt": null,
      "files": []
    }
  ]
}

Additionnaly, you can retrieve a single thread with its id.

Close a thread

curl "https://api.colizey.fr/merchant/messenger/threads/{threadId}/close" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -X POST

Example response

{
  "order": {
    "id": "cc511c09-b792-4202-88e8-71c50e758d9e",
    "orderNumber": "XXX"
  },
  "user": {
    "firstName": "Firstname",
    "lastName": "Lastname"
  },
  "id": "0d82d3c4-653f-47ac-b4e9-31b9106ba73a",
  "subject": "order",
  "createdAt": "2022-05-23T14:30:34+00:00",
  "updatedAt": "2022-05-23T14:34:19+00:00",
  "author": 1,
  "actionMerchantNeeded": false,
  "closed": true,
  "messages": [
    {
      "id": "1c63b3a0-3d39-4fee-b4e8-3f053a68b8d1",
      "message": "Lorem Ipsum",
      "author": 1,
      "createdAt": "2022-05-23T14:34:19+00:00",
      "readAt": null,
      "files": []
    }
  ]
}

Once a thread is considered as solved, you can close it.

Attach files

With the Messenger API, you have the possibility to attach a file to a thread.

To attach a file to a thread, you must upload it beforehand.

Available extensions

Only some type of files can be uploaded, here is the list of the available ones:

Extensions
.odt
.doc
.docx
.pdf
.jpeg
.png

Upload a file

curl "https://api.colizey.fr/merchant/messenger/files" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F "files[0]=@'/path/to/file1.pdf'" \
  -F "files[1]=@'/path/to/file2.pdf'" \
  -X POST

Example response

{
    "files": [
        {
            "id": "7b807de6-b6f2-4bc2-b338-8e90ce0b15c2",
            "name": "file1.png",
            "url": "https://example.url/messenger/file/7b807de6-b6f2-4bc2-b338-8e90ce0b15c2"
        }
    ],
    "errors": []
}

Once uploaded, you can use file ids as parameters with the Create a thread or Add a message to a thread endpoints.

Changelog

2023-04-10 v1.3.9

2022-05-24 v1.0.0

Initial release.

shell php