API Reference

Generate realistic chat mockup images programmatically. Perfect for automating content creation, building integrations, or creating mockups at scale.

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

http

Base URL

All API endpoints are relative to the following base URL:

https://www.getmockly.com/api/v1

url

Generate Chat Image

POST/chat/image

Generate a PNG image of a chat conversation. The image is rendered using the same engine that powers the Mockly web application, ensuring pixel-perfect results.

Request Body

platformstringrequired

The messaging platform to render. One of: discord, imessage, instagram, line, messenger, microsoftTeams, reddit, signal, slack, snapchat, telegram, tiktok, tinder, wechat, whatsapp, x

senderUserrequired

The user sending messages. Object with id (string), name (string), and optional image (base64 data URL).

receiversUser[]required

Array of recipient users. Each with id, name, and optional image.

messagesMessage[]required

Array of messages to display. See Message schema below.

conversationTypestring

Type of conversation: direct-message (default) or group-chat.

darkModeboolean

Enable dark mode theme. Default: false

mobileViewboolean

Render in mobile dimensions. Default: true

showHeaderboolean

Show the chat header. Default: true

showFooterboolean

Show the message input footer. Default: true

timeNotationstring

Time format: 12h or 24h (default).

transparentBackgroundboolean

Render with transparent background. Default: false

groupChatSettingsobject

For group chats: object with name (string) and optional image (base64).

Message Schema

idstringrequired

Unique identifier for the message.

textstring

Message text content. Optional if the message contains only images.

timestampstringrequired

ISO 8601 timestamp (e.g., 2025-01-15T10:30:00Z).

typestringrequired

Message type: text, image, or mixed.

userIdstringrequired

ID of the user who sent this message (must match sender or a receiver).

statusstring

Delivery status: sent, delivered, or read.

imagesMessageImage[]

Array of images attached to the message.

Response

On success, returns a JSON object with the base64-encoded PNG image:

{
  "type": "success",
  "data": {
    "image": "iVBORw0KGgoAAAANSUhEUgAA...", // base64-encoded PNG
    "mimeType": "image/png",
    "sizeInBytes": 145832
  }
}

json

Code Examples

cURL

curl -X POST https://www.getmockly.com/api/v1/chat/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "whatsapp",
    "sender": {
      "id": "sender-1",
      "name": "Alice"
    },
    "receivers": [{
      "id": "receiver-1",
      "name": "Bob"
    }],
    "messages": [{
      "id": "msg-1",
      "text": "Hey! How are you?",
      "timestamp": "2025-01-15T10:30:00Z",
      "type": "text",
      "userId": "sender-1"
    }, {
      "id": "msg-2",
      "text": "I am doing great, thanks!",
      "timestamp": "2025-01-15T10:31:00Z",
      "type": "text",
      "userId": "receiver-1"
    }]
  }'

bash

TypeScript / JavaScript

const response = await fetch("https://www.getmockly.com/api/v1/chat/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "whatsapp",
    sender: { id: "sender-1", name: "Alice" },
    receivers: [{ id: "receiver-1", name: "Bob" }],
    messages: [
      {
        id: "msg-1",
        text: "Hey! How are you?",
        timestamp: "2025-01-15T10:30:00Z",
        type: "text",
        userId: "sender-1",
      },
      {
        id: "msg-2",
        text: "I am doing great, thanks!",
        timestamp: "2025-01-15T10:31:00Z",
        type: "text",
        userId: "receiver-1",
      },
    ],
  }),
});

const data = await response.json();

if (data.type === "success") {
  // data.data.image contains the base64-encoded PNG
  const imageUrl = `data:${data.data.mimeType};base64,${data.data.image}`;
  console.log("Image size:", data.data.sizeInBytes, "bytes");
}

typescript

Python

import requests
import base64

response = requests.post(
    "https://www.getmockly.com/api/v1/chat/image",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "platform": "whatsapp",
        "sender": {"id": "sender-1", "name": "Alice"},
        "receivers": [{"id": "receiver-1", "name": "Bob"}],
        "messages": [
            {
                "id": "msg-1",
                "text": "Hey! How are you?",
                "timestamp": "2025-01-15T10:30:00Z",
                "type": "text",
                "userId": "sender-1",
            },
            {
                "id": "msg-2",
                "text": "I am doing great, thanks!",
                "timestamp": "2025-01-15T10:31:00Z",
                "type": "text",
                "userId": "receiver-1",
            },
        ],
    },
)

data = response.json()

if data["type"] == "success":
    # Save the image to a file
    image_data = base64.b64decode(data["data"]["image"])
    with open("chat_mockup.png", "wb") as f:
        f.write(image_data)
    print(f"Image saved! Size: {data['data']['sizeInBytes']} bytes")

python

Error Handling

The API returns consistent error responses with a type: "error" field and a descriptive message.

401Unauthorized

Invalid or missing API key.

{
  "type": "error",
  "message": "Invalid API key"
}

json

400Bad Request

Invalid request body or validation errors.

{
  "type": "error",
  "message": "Invalid request body",
  "errors": {
    "platform": ["Invalid enum value"],
    "messages": ["Required"]
  }
}

json

500Internal Server Error

Server-side error during image generation. The message field will contain details.

Rate Limits

API requests are rate-limited to ensure fair usage. If you exceed the rate limit, you will receive a 429 Too Many Requests response. Contact us if you need higher limits for your use case: maurice@getmockly.com.