Skip to main content

Emoji API

The Emoji API allows you to manage individual emojis, including Unicode emojis, custom images, and CSS sprite-based emojis.

Base URL

/api/emoji/emojis

Endpoints

List Emoji

Get a paginated list of emojis with optional filtering and relationship loading.

GET /api/emoji/emojis

Query Parameters

ParameterTypeDescription
category_idintegerFilter by category ID
searchstringSearch in shortcode, title, or emoji text
with_categorybooleanInclude category information
with_aliasesbooleanInclude emoji aliases
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 50, max: 100)

Example Request

curl -X GET "https://api.example.com/api/emoji/emojis?category_id=1&with_aliases=1&per_page=25" \
-H "Accept: application/json"

Example Response

{
"data": [
{
"id": 1,
"title": "Grinning Face",
"emoji_text": "😀",
"emoji_shortcode": ":grinning:",
"image_url": null,
"sprite_mode": false,
"sprite_params": null,
"display_order": 1,
"category": {
"id": 1,
"title": "Smileys",
"display_order": 1,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
},
"aliases": [
{
"id": 1,
"alias": ":grin:",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
],
"aliases_count": 1,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
],
"links": {
"first": "https://api.example.com/api/emoji/emojis?page=1",
"last": "https://api.example.com/api/emoji/emojis?page=3",
"prev": null,
"next": "https://api.example.com/api/emoji/emojis?page=2"
},
"meta": {
"current_page": 1,
"per_page": 25,
"total": 67
}
}

Search Emoji

Search emojis using Laravel Scout for full-text search capabilities.

GET /api/emoji/emojis/search

Query Parameters

ParameterTypeRequiredDescription
qstringYesSearch query (minimum 1 character)
limitintegerNoNumber of results (default: 20, max: 100)
with_categorybooleanNoInclude category information
with_aliasesbooleanNoInclude emoji aliases

Example Request

curl -X GET "https://api.example.com/api/emoji/emojis/search?q=smile&limit=10&with_category=1" \
-H "Accept: application/json"

Example Response

{
"data": [
{
"id": 1,
"title": "Smiling Face",
"emoji_text": "😊",
"emoji_shortcode": ":smile:",
"image_url": null,
"sprite_mode": false,
"sprite_params": null,
"display_order": 2,
"category": {
"id": 1,
"title": "Smileys",
"display_order": 1,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
},
"aliases": null,
"aliases_count": null,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
]
}

Get Emoji

Get a specific emoji by ID with full relationship data.

GET /api/emoji/emojis/{id}

Path Parameters

ParameterTypeDescription
idintegerThe emoji ID

Example Request

curl -X GET "https://api.example.com/api/emoji/emojis/1" \
-H "Accept: application/json"

Example Response

{
"data": {
"id": 1,
"title": "Grinning Face",
"emoji_text": "😀",
"emoji_shortcode": ":grinning:",
"image_url": null,
"sprite_mode": false,
"sprite_params": null,
"display_order": 1,
"category": {
"id": 1,
"title": "Smileys",
"display_order": 1,
"emojis_count": null,
"emojis": null,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
},
"aliases": [
{
"id": 1,
"alias": ":grin:",
"emoji": null,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
],
"aliases_count": null,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
}

Create Emoji

Create a new emoji. Supports Unicode emojis, custom images, and CSS sprites.

POST /api/emoji/emojis

Request Body

FieldTypeRequiredDescription
titlestringYesHuman-readable name (max 255 chars)
emoji_textstringNoUnicode emoji or text emoticon (max 10 chars)
emoji_shortcodestringYesPrimary shortcode in :name: format (unique)
image_urlstringNoPath to custom image (max 500 chars)
sprite_modebooleanNoWhether to use CSS sprite mode (default: false)
sprite_paramsobjectNoSprite parameters (required if sprite_mode is true)
sprite_params.xintegerConditionalX coordinate (required if sprite_mode is true)
sprite_params.yintegerConditionalY coordinate (required if sprite_mode is true)
sprite_params.widthintegerConditionalSprite width (required if sprite_mode is true)
sprite_params.heightintegerConditionalSprite height (required if sprite_mode is true)
sprite_params.sheetstringConditionalSprite sheet filename (required if sprite_mode is true)
emoji_category_idintegerNoCategory ID (must exist)
display_orderintegerYesDisplay order within category (minimum 0)

Example Requests

Unicode Emoji:

curl -X POST "https://api.example.com/api/emoji/emojis" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"title": "Heart Eyes",
"emoji_text": "😍",
"emoji_shortcode": ":heart_eyes:",
"emoji_category_id": 1,
"display_order": 5
}'

Custom Image Emoji:

curl -X POST "https://api.example.com/api/emoji/emojis" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"title": "Party Parrot",
"emoji_shortcode": ":partyparrot:",
"image_url": "/emojis/custom/partyparrot.gif",
"emoji_category_id": 2,
"display_order": 1
}'

CSS Sprite Emoji:

curl -X POST "https://api.example.com/api/emoji/emojis" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"title": "Custom Sprite",
"emoji_shortcode": ":custom_sprite:",
"sprite_mode": true,
"sprite_params": {
"x": 32,
"y": 64,
"width": 32,
"height": 32,
"sheet": "emoji-sheet-1.png"
},
"emoji_category_id": 3,
"display_order": 10
}'

Example Response

{
"data": {
"id": 25,
"title": "Heart Eyes",
"emoji_text": "😍",
"emoji_shortcode": ":heart_eyes:",
"image_url": null,
"sprite_mode": false,
"sprite_params": null,
"display_order": 5,
"category": null,
"aliases": null,
"aliases_count": null,
"created_at": "2025-01-01T12:00:00Z",
"updated_at": "2025-01-01T12:00:00Z"
}
}

Update Emoji

Update an existing emoji.

PUT /api/emoji/emojis/{id}
PATCH /api/emoji/emojis/{id}

Path Parameters

ParameterTypeDescription
idintegerThe emoji ID

Request Body

All fields from the create endpoint are supported, but all are optional for updates.

Example Request

curl -X PATCH "https://api.example.com/api/emoji/emojis/25" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"title": "Love Eyes",
"display_order": 6
}'

Example Response

{
"data": {
"id": 25,
"title": "Love Eyes",
"emoji_text": "😍",
"emoji_shortcode": ":heart_eyes:",
"image_url": null,
"sprite_mode": false,
"sprite_params": null,
"display_order": 6,
"category": null,
"aliases": null,
"aliases_count": null,
"created_at": "2025-01-01T12:00:00Z",
"updated_at": "2025-01-01T12:30:00Z"
}
}

Delete Emoji

Delete an emoji. Associated aliases will be automatically deleted.

DELETE /api/emoji/emojis/{id}

Path Parameters

ParameterTypeDescription
idintegerThe emoji ID

Example Request

curl -X DELETE "https://api.example.com/api/emoji/emojis/25" \
-H "Accept: application/json"

Example Response

HTTP/1.1 204 No Content

Error Responses

422 Validation Error

{
"message": "The given data was invalid.",
"errors": {
"emoji_shortcode": [
"The emoji shortcode must be in the format :name: (e.g., :smile:)",
"This shortcode is already taken."
],
"sprite_params.x": [
"The sprite params.x field is required when sprite mode is true."
]
}
}

400 Search Validation Error

{
"message": "The given data was invalid.",
"errors": {
"q": ["The q field is required."],
"limit": ["The limit must not be greater than 100."]
}
}

Emoji Types

The API supports three types of emojis:

1. Unicode Emoji

  • Have emoji_text field set to the Unicode character
  • image_url and sprite_params are null
  • sprite_mode is false

2. Custom Image Emoji

  • Have image_url field set to the image path
  • emoji_text and sprite_params are null
  • sprite_mode is false

3. CSS Sprite Emoji

  • Have sprite_mode set to true
  • Have sprite_params object with position and dimensions
  • emoji_text and image_url are null

Validation Rules

  • emoji_shortcode: Must be unique across all emojis and cannot conflict with any alias
  • Aliases: Cannot conflict with any existing emoji shortcode
  • Format: All shortcodes and aliases must follow the :name: pattern
  • Sprite params: Required when sprite_mode is true
  • Category: Must reference an existing category if provided

Notes

  • Emoji are returned ordered by display_order ascending
  • When an emoji is deleted, all associated aliases are automatically deleted (cascade)
  • Search functionality uses Laravel Scout for fast full-text search
  • The aliases_count field is only included when aliases are not loaded
  • Maximum search results per request is 100