POST /api/v1/chat/upload-image — send an image

Use this endpoint to upload an image file and send it as a message in a chat conversation. The request uses multipart/form-data instead of JSON, so you include the image binary alongside the recipient ID as form fields. The server stores the image and returns a URL you can use to display it.

Endpoint

POST /api/v1/chat/upload-image

Authentication

Bearer token required. See Authentication.

Request format

multipart/form-data — do not set Content-Type: application/json for this endpoint. Your HTTP client or library will set the correct multipart content type automatically when you attach a file.

Supported formats

JPEG, PNG, WebP, GIF.

Form fields

imagefilebodyrequired

The image file to upload. Supported formats: JPEG, PNG, WebP, GIF.

handymanIdstringbody

ID of the handyman recipient. Provide this when a partner or admin is sending to a handyman.

partnerIdstringbody

ID of the partner recipient. Provide this when a handyman or admin is sending to a partner.

adminIdstringbody

ID of the admin recipient. Provide this when a partner or handyman is sending to an admin.

Note

Exactly one of handymanId, partnerId, or adminId must be included in every request.

Example

curl -X POST "https://<your-portal-domain>/api/v1/chat/upload-image" \
  -H "Authorization: Bearer <your-token>" \
  -F "image=@/path/to/image.jpg" \
  -F "handymanId=handyman_xyz456"

Success response

Returns 200 OK with the created message object nested under data.

idstring

Unique identifier for the message.

roomIdstring

The chat room this message belongs to.

senderIdstring

ID of the user who sent the image (your authenticated user).

messageTypestring

Always "image" for this endpoint.

imageUrlstring

Public URL of the uploaded image that can be used to display it in your application.

imageSizestring

JSON-encoded string containing fileSize (bytes) and mimeType of the uploaded image.

createdAtstring

ISO 8601 timestamp of when the message was created.

{
  "message": "Image uploaded and sent successfully",
  "data": {
    "id": "msg_123456",
    "roomId": "room_admin_handyman_xyz456",
    "senderId": "user_xyz456",
    "messageType": "image",
    "imageUrl": "https://storage.example.com/chat/image.jpg",
    "imageSize": "{\"fileSize\":123456,\"mimeType\":\"image/jpeg\"}",
    "createdAt": "2024-01-16T10:30:00.000Z"
  }
}

Error responses

Status	Error message	Cause
400	`"partnerId, handymanId, or adminId is required"`	No recipient ID was provided
400	`"Admin can only chat with either partner or handyman, not both"`	Admin provided more than one recipient ID
400	`"Invalid recipient role"`	The recipient ID does not match a valid role
403	`"Handyman and partner are not connected"`	The handyman and partner are not linked through a job or installation
404	`"Recipient user not found"`	No user exists with the given ID
500	`"Internal server error"`	An unexpected error occurred on the server