{
  "openapi": "3.1.0",
  "info": {
    "title": "RCS API",
    "version": "3.0.0",
    "description": "Send verified RCS Business Messaging through the iP1 platform.",
    "termsOfService": "https://ip1sms.web.app/en/agreements/service-agreement",
    "contact": {
      "name": "iP1 Support",
      "email": "support@ip1.se"
    },
    "license": {
      "name": "Proprietary – iP.1 service agreement",
      "url": "https://ip1sms.web.app/en/agreements/service-agreement"
    }
  },
  "servers": [
    {
      "url": "https://api.ip1.net/v3",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "RCS API developer documentation",
    "url": "https://rcs-api.com/en/documentation/"
  },
  "tags": [
    {
      "name": "Getting started"
    },
    {
      "name": "Brands & agents"
    },
    {
      "name": "Bundles"
    },
    {
      "name": "Conversations"
    },
    {
      "name": "Messages"
    }
  ],
  "paths": {
    "/phones/{msisdn}/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "tags": [
          "Getting started"
        ],
        "summary": "Check whether the recipient supports RCS",
        "description": "Returns RCS availability and supported features for a recipient.",
        "responses": {
          "200": {
            "description": "Capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CapabilityResponse"
                },
                "example": {
                  "rcs": true,
                  "features": [
                    "CARD",
                    "CAROUSEL",
                    "SUGGESTIONS"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Kontrollera om mottagarens enhet stöder RCS",
          "en": "Check whether the recipient supports RCS"
        },
        "x-description": {
          "sv": "Returnerar mottagarens RCS-stöd och tillgängliga funktioner.",
          "en": "Returns RCS availability and supported features for a recipient."
        },
        "x-group": {
          "sv": "Introduktion",
          "en": "Getting started"
        },
        "x-doc": {
          "sv": "/dokumentation/introduktion/kontrollera-om-mottagarens-enhet-stoder-rcs/",
          "en": "/en/documentation/introduction/check-if-the-recipients-device-supports-rcs/"
        },
        "parameters": [
          {
            "name": "msisdn",
            "in": "path",
            "required": true,
            "description": "Recipient number in international format.",
            "x-description": {
              "sv": "Mottagarens nummer i internationellt format.",
              "en": "Recipient number in international format."
            },
            "schema": {
              "type": "string",
              "pattern": "^\\+?[1-9]\\d{7,14}$"
            },
            "example": "46700123456"
          }
        ]
      }
    },
    "/brands": {
      "get": {
        "operationId": "listBrands",
        "tags": [
          "Brands & agents"
        ],
        "summary": "List registered brands",
        "description": "Lists brands registered for the account.",
        "responses": {
          "200": {
            "description": "Brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Brand"
                  }
                },
                "example": [
                  {
                    "name": "ip1-demo",
                    "displayName": "iP1 Demo"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Lista registrerade varumärken",
          "en": "List registered brands"
        },
        "x-description": {
          "sv": "Listar varumärken som tillhör kontot.",
          "en": "Lists brands registered for the account."
        },
        "x-group": {
          "sv": "Brands & agenter",
          "en": "Brands & agents"
        },
        "x-doc": {
          "sv": "/dokumentation/introduktion/skapa-en-agent/",
          "en": "/en/documentation/introduction/create-an-agent/"
        }
      },
      "post": {
        "operationId": "createBrand",
        "tags": [
          "Brands & agents"
        ],
        "summary": "Register a brand",
        "description": "Registers a new RCS brand.",
        "responses": {
          "201": {
            "description": "Brand created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Brand"
                },
                "example": {
                  "name": "min-butik-ab",
                  "displayName": "Min Butik AB"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Registrera ett varumärke",
          "en": "Register a brand"
        },
        "x-description": {
          "sv": "Registrerar ett nytt RCS-varumärke.",
          "en": "Registers a new RCS brand."
        },
        "x-group": {
          "sv": "Brands & agenter",
          "en": "Brands & agents"
        },
        "x-doc": {
          "sv": "/dokumentation/introduktion/skapa-en-agent/",
          "en": "/en/documentation/introduction/create-an-agent/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrandRequest"
              },
              "example": {
                "name": "min-butik-ab",
                "displayName": "Min Butik AB"
              }
            }
          }
        }
      }
    },
    "/brands/{brandName}/agents": {
      "get": {
        "operationId": "listAgents",
        "tags": [
          "Brands & agents"
        ],
        "summary": "List agents for a brand",
        "description": "Lists sender profiles registered for a brand.",
        "responses": {
          "200": {
            "description": "Agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Agent"
                  }
                },
                "example": [
                  {
                    "name": "support",
                    "displayName": "Support",
                    "status": "VERIFIED"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Lista agenter för ett varumärke",
          "en": "List agents for a brand"
        },
        "x-description": {
          "sv": "Listar avsändarprofiler för ett varumärke.",
          "en": "Lists sender profiles registered for a brand."
        },
        "x-group": {
          "sv": "Brands & agenter",
          "en": "Brands & agents"
        },
        "x-doc": {
          "sv": "/dokumentation/introduktion/skapa-en-agent/",
          "en": "/en/documentation/introduction/create-an-agent/"
        },
        "parameters": [
          {
            "name": "brandName",
            "in": "path",
            "required": true,
            "description": "Unique brand name.",
            "x-description": {
              "sv": "Unikt namn för varumärket.",
              "en": "Unique brand name."
            },
            "schema": {
              "type": "string"
            },
            "example": "ip1-demo"
          }
        ]
      },
      "post": {
        "operationId": "createAgent",
        "tags": [
          "Brands & agents"
        ],
        "summary": "Create an agent",
        "description": "Creates a sender profile for a brand.",
        "responses": {
          "201": {
            "description": "Agent created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                },
                "example": {
                  "name": "support",
                  "displayName": "Support",
                  "status": "PENDING"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Skapa en agent",
          "en": "Create an agent"
        },
        "x-description": {
          "sv": "Skapar en avsändarprofil under ett varumärke.",
          "en": "Creates a sender profile for a brand."
        },
        "x-group": {
          "sv": "Brands & agenter",
          "en": "Brands & agents"
        },
        "x-doc": {
          "sv": "/dokumentation/introduktion/skapa-en-agent/",
          "en": "/en/documentation/introduction/create-an-agent/"
        },
        "parameters": [
          {
            "name": "brandName",
            "in": "path",
            "required": true,
            "description": "Unique brand name.",
            "x-description": {
              "sv": "Unikt namn för varumärket.",
              "en": "Unique brand name."
            },
            "schema": {
              "type": "string"
            },
            "example": "ip1-demo"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRequest"
              },
              "example": {
                "name": "support",
                "displayName": "Support"
              }
            }
          }
        }
      }
    },
    "/bundles": {
      "get": {
        "operationId": "listBundles",
        "tags": [
          "Bundles"
        ],
        "summary": "List multi-recipient sends",
        "description": "Returns previous bundle sends and their status.",
        "responses": {
          "200": {
            "description": "Bundles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SendResponse"
                  }
                },
                "example": [
                  {
                    "id": "bnd_01JRC5N8",
                    "status": "ACCEPTED"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Lista utskick till flera mottagare",
          "en": "List multi-recipient sends"
        },
        "x-description": {
          "sv": "Returnerar tidigare bundle-utskick och deras status.",
          "en": "Returns previous bundle sends and their status."
        },
        "x-group": {
          "sv": "Bundles",
          "en": "Bundles"
        },
        "x-doc": {
          "sv": "/dokumentation/bundles/hantera-bundles/",
          "en": "/en/documentation/bundles/handle-bundles/"
        },
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "description": "Optional campaign tag.",
            "x-description": {
              "sv": "Valfri kampanjtagg.",
              "en": "Optional campaign tag."
            },
            "schema": {
              "type": "string"
            },
            "example": "campaign-2026"
          }
        ]
      },
      "post": {
        "operationId": "createBundle",
        "tags": [
          "Bundles"
        ],
        "summary": "Send RCS to multiple recipients",
        "description": "Sends the same RCS content to multiple recipients.",
        "responses": {
          "202": {
            "description": "Bundle accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                },
                "example": {
                  "id": "bnd_01JRC5N8",
                  "status": "ACCEPTED"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Skicka RCS till flera mottagare",
          "en": "Send RCS to multiple recipients"
        },
        "x-description": {
          "sv": "Skickar samma RCS-innehåll till flera mottagare.",
          "en": "Sends the same RCS content to multiple recipients."
        },
        "x-group": {
          "sv": "Bundles",
          "en": "Bundles"
        },
        "x-doc": {
          "sv": "/dokumentation/bundles/skicka-rcs/",
          "en": "/en/documentation/bundles/send-rcs/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BundleRequest"
              },
              "example": {
                "brand": "ip1-demo",
                "agent": "support",
                "recipients": {
                  "46700123456": {},
                  "46700987654": {}
                },
                "type": "Text",
                "content": "Hello from RCS"
              }
            }
          }
        }
      }
    },
    "/conversations": {
      "get": {
        "operationId": "listConversations",
        "tags": [
          "Conversations"
        ],
        "summary": "List conversations",
        "description": "Returns active and completed RCS conversations.",
        "responses": {
          "200": {
            "description": "Conversations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Conversation"
                  }
                },
                "example": [
                  {
                    "id": "cnv_01JRC5N8",
                    "agent": "support",
                    "recipient": "46700123456",
                    "status": "ACTIVE"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Lista konversationer",
          "en": "List conversations"
        },
        "x-description": {
          "sv": "Returnerar pågående och avslutade RCS-konversationer.",
          "en": "Returns active and completed RCS conversations."
        },
        "x-group": {
          "sv": "Konversationer",
          "en": "Conversations"
        },
        "x-doc": {
          "sv": "/dokumentation/konversationer/hantera-konversationer/",
          "en": "/en/documentation/conversations/manage-conversations/"
        }
      },
      "post": {
        "operationId": "createConversation",
        "tags": [
          "Conversations"
        ],
        "summary": "Start a conversation",
        "description": "Starts a new RCS conversation with one recipient.",
        "responses": {
          "201": {
            "description": "Conversation created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                },
                "example": {
                  "id": "cnv_01JRC5N8",
                  "status": "ACCEPTED"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Starta en konversation",
          "en": "Start a conversation"
        },
        "x-description": {
          "sv": "Startar en ny RCS-konversation med en mottagare.",
          "en": "Starts a new RCS conversation with one recipient."
        },
        "x-group": {
          "sv": "Konversationer",
          "en": "Conversations"
        },
        "x-doc": {
          "sv": "/dokumentation/konversationer/skapa-konversation/",
          "en": "/en/documentation/conversations/create-conversation/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversationRequest"
              },
              "example": {
                "brand": "ip1-demo",
                "agent": "iP1 Demo",
                "recipient": "46700123456",
                "type": "Card",
                "card": {
                  "title": "Skapa rikare kunddialoger",
                  "content": "Skicka högupplösta bilder, video och interaktiva val direkt i meddelandeappen.",
                  "mediaUrl": "/media/2026-09-rcs-high-definition-media.webp",
                  "height": "Medium",
                  "orientation": "Vertical"
                },
                "suggestions": [
                  {
                    "text": "Utforska RCS",
                    "type": "OpenUrlAction",
                    "url": "https://rcs-api.com/guide/",
                    "postbackData": "explore=rcs"
                  },
                  {
                    "text": "Kontakta oss",
                    "type": "Reply",
                    "postbackData": "contact=sales"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/bundles/{bundle}/messages": {
      "get": {
        "operationId": "listBundleMessages",
        "tags": [
          "Messages"
        ],
        "summary": "List messages in a bundle",
        "description": "Returns individual messages and delivery status for a bundle.",
        "responses": {
          "200": {
            "description": "Messages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Message"
                  }
                },
                "example": [
                  {
                    "id": "msg_01JRC5N8",
                    "recipient": "46700123456",
                    "status": "DELIVERED"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Lista meddelanden i en bundle",
          "en": "List messages in a bundle"
        },
        "x-description": {
          "sv": "Returnerar enskilda meddelanden och leveransstatus i en bundle.",
          "en": "Returns individual messages and delivery status for a bundle."
        },
        "x-group": {
          "sv": "Meddelanden",
          "en": "Messages"
        },
        "x-doc": {
          "sv": "/dokumentation/meddelanden/lista-meddelanden-i-en-bundle/",
          "en": "/en/documentation/messages/list-messages-in-a-bundle/"
        },
        "parameters": [
          {
            "name": "bundle",
            "in": "path",
            "required": true,
            "description": "Bundle identifier.",
            "x-description": {
              "sv": "Bundle-identifierare.",
              "en": "Bundle identifier."
            },
            "schema": {
              "type": "string"
            },
            "example": "bnd_01JRC5N8"
          }
        ]
      }
    },
    "/messages/{messageId}/cards": {
      "get": {
        "operationId": "getMessageCards",
        "tags": [
          "Messages"
        ],
        "summary": "Get cards for a message",
        "description": "Returns rich cards attached to a message.",
        "responses": {
          "200": {
            "description": "Cards",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Card"
                  }
                },
                "example": [
                  {
                    "title": "Skapa rikare kunddialoger",
                    "content": "Skicka högupplösta bilder, video och interaktiva val direkt i meddelandeappen.",
                    "mediaUrl": "/media/2026-09-rcs-high-definition-media.webp",
                    "height": "Medium",
                    "orientation": "Vertical"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Hämta cards för ett meddelande",
          "en": "Get cards for a message"
        },
        "x-description": {
          "sv": "Returnerar rich cards som hör till ett meddelande.",
          "en": "Returns rich cards attached to a message."
        },
        "x-group": {
          "sv": "Meddelanden",
          "en": "Messages"
        },
        "x-doc": {
          "sv": "/dokumentation/meddelanden/cards/",
          "en": "/en/documentation/messages/cards/"
        },
        "parameters": [
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "description": "Message identifier.",
            "x-description": {
              "sv": "Meddelande-identifierare.",
              "en": "Message identifier."
            },
            "schema": {
              "type": "string"
            },
            "example": "msg_01JRC5N8"
          }
        ]
      }
    },
    "/messages/{messageId}/suggestions": {
      "get": {
        "operationId": "getMessageSuggestions",
        "tags": [
          "Messages"
        ],
        "summary": "Get suggestions and actions",
        "description": "Returns suggested replies and actions.",
        "responses": {
          "200": {
            "description": "Suggestions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Suggestion"
                  }
                },
                "example": [
                  {
                    "text": "Open website",
                    "type": "OpenUrlAction",
                    "url": "https://example.com"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "The request payload is invalid."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "A valid bearer token is required."
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-summary": {
          "sv": "Hämta förslag och knappar",
          "en": "Get suggestions and actions"
        },
        "x-description": {
          "sv": "Returnerar föreslagna svar och åtgärder.",
          "en": "Returns suggested replies and actions."
        },
        "x-group": {
          "sv": "Meddelanden",
          "en": "Messages"
        },
        "x-doc": {
          "sv": "/dokumentation/meddelanden/forslag/",
          "en": "/en/documentation/messages/suggestion/"
        },
        "parameters": [
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "description": "Message identifier.",
            "x-description": {
              "sv": "Meddelande-identifierare.",
              "en": "Message identifier."
            },
            "schema": {
              "type": "string"
            },
            "example": "msg_01JRC5N8"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API token"
      }
    },
    "schemas": {
      "ConversationRequest": {
        "type": "object",
        "required": [
          "brand",
          "agent",
          "recipient",
          "type"
        ],
        "x-requiredByType": {
          "Text": [
            "content"
          ],
          "Card": [
            "card"
          ],
          "Carousel": [
            "carousel"
          ]
        },
        "properties": {
          "brand": {
            "type": "string",
            "minLength": 1
          },
          "agent": {
            "type": "string",
            "minLength": 1
          },
          "recipient": {
            "type": "string",
            "pattern": "^\\+?[1-9]\\d{7,14}$"
          },
          "type": {
            "type": "string",
            "enum": [
              "Text",
              "Card",
              "Carousel"
            ]
          },
          "content": {
            "type": "string",
            "minLength": 1
          },
          "card": {
            "$ref": "#/components/schemas/Card"
          },
          "carousel": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Card"
            }
          },
          "suggestions": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/Suggestion"
            }
          },
          "fallbackPolicy": {
            "type": "string"
          },
          "fallbackMessage": {
            "type": "string"
          }
        }
      },
      "BundleRequest": {
        "type": "object",
        "required": [
          "brand",
          "agent",
          "recipients",
          "type"
        ],
        "properties": {
          "brand": {
            "type": "string"
          },
          "agent": {
            "type": "string"
          },
          "recipients": {
            "type": "object",
            "minProperties": 1
          },
          "type": {
            "type": "string",
            "enum": [
              "Text",
              "Card",
              "Carousel"
            ]
          },
          "content": {
            "type": "string"
          },
          "card": {
            "$ref": "#/components/schemas/Card"
          },
          "carousel": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Card"
            }
          }
        }
      },
      "Card": {
        "type": "object",
        "required": [
          "title",
          "content"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "mediaUrl": {
            "type": "string",
            "format": "uri-reference"
          },
          "height": {
            "type": "string",
            "enum": [
              "Short",
              "Medium",
              "Tall"
            ]
          },
          "orientation": {
            "type": "string",
            "enum": [
              "Vertical",
              "Horizontal"
            ]
          },
          "suggestions": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/Suggestion"
            }
          }
        }
      },
      "Suggestion": {
        "type": "object",
        "required": [
          "text",
          "type"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1
          },
          "type": {
            "type": "string",
            "enum": [
              "Reply",
              "OpenUrlAction",
              "DialAction",
              "ViewLocationAction"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "postbackData": {
            "type": "string"
          }
        }
      },
      "BrandRequest": {
        "type": "object",
        "required": [
          "name",
          "displayName"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          }
        }
      },
      "AgentRequest": {
        "type": "object",
        "required": [
          "name",
          "displayName"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          }
        }
      },
      "Brand": {
        "type": "object",
        "required": [
          "name",
          "displayName"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "CapabilityResponse": {
        "type": "object",
        "properties": {
          "rcs": {
            "type": "boolean"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "SendResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "agent": {
            "type": "string"
          },
          "recipient": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "recipient": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-playgroundTemplates": [
    {
      "id": "text",
      "label": {
        "sv": "Text",
        "en": "Text"
      },
      "description": {
        "sv": "Ett enkelt RCS-textmeddelande",
        "en": "A simple RCS text message"
      },
      "payload": {
        "brand": "ip1-demo",
        "agent": "iP1 Demo",
        "recipient": "46700123456",
        "type": "Text",
        "content": "Din verifieringskod är 849201"
      }
    },
    {
      "id": "card",
      "label": {
        "sv": "Rich card",
        "en": "Rich card"
      },
      "description": {
        "sv": "Bild, innehåll och interaktiva val",
        "en": "Image, content and actions"
      },
      "payload": {
        "brand": "ip1-demo",
        "agent": "iP1 Demo",
        "recipient": "46700123456",
        "type": "Card",
        "card": {
          "title": "Skapa rikare kunddialoger",
          "content": "Skicka högupplösta bilder, video och interaktiva val direkt i meddelandeappen.",
          "mediaUrl": "/media/2026-09-rcs-high-definition-media.webp",
          "height": "Medium",
          "orientation": "Vertical"
        },
        "suggestions": [
          {
            "text": "Utforska RCS",
            "type": "OpenUrlAction",
            "url": "https://rcs-api.com/guide/",
            "postbackData": "explore=rcs"
          },
          {
            "text": "Kontakta oss",
            "type": "Reply",
            "postbackData": "contact=sales"
          }
        ]
      }
    },
    {
      "id": "carousel",
      "label": {
        "sv": "Karusell",
        "en": "Carousel"
      },
      "description": {
        "sv": "Flera bläddringsbara RCS-kort",
        "en": "Multiple swipeable RCS cards"
      },
      "payload": {
        "brand": "ip1-demo",
        "agent": "iP1 Demo",
        "recipient": "46700123456",
        "type": "Carousel",
        "carousel": [
          {
            "title": "Premium",
            "content": "Vårt mest kompletta paket.",
            "mediaUrl": "/media/2026-09-rcs-high-definition-media.webp",
            "height": "Medium"
          },
          {
            "title": "Business",
            "content": "Flexibelt för växande team.",
            "mediaUrl": "/media/2025-10-man-som-laser-rcs-skickat-fran-rcs-api.webp",
            "height": "Medium"
          }
        ],
        "suggestions": [
          {
            "text": "Jämför paket",
            "type": "OpenUrlAction",
            "url": "https://rcs-api.com/"
          }
        ]
      }
    },
    {
      "id": "otp",
      "label": {
        "sv": "OTP / 2FA",
        "en": "OTP / 2FA"
      },
      "description": {
        "sv": "Verifierad engångskod med kopieringsknapp",
        "en": "Verified one-time code"
      },
      "payload": {
        "brand": "ip1-demo",
        "agent": "Verifiering",
        "recipient": "46700123456",
        "type": "Text",
        "content": "Din verifieringskod är 849201. Koden gäller i 10 minuter.",
        "suggestions": [
          {
            "text": "Kopiera 849201",
            "type": "Reply",
            "postbackData": "otp=849201"
          }
        ]
      }
    },
    {
      "id": "fallback",
      "label": {
        "sv": "SMS fallback",
        "en": "SMS fallback"
      },
      "description": {
        "sv": "RCS med automatisk SMS-reserv",
        "en": "RCS with automatic SMS fallback"
      },
      "payload": {
        "brand": "ip1-demo",
        "agent": "iP1 Demo",
        "recipient": "46700123456",
        "type": "Card",
        "card": {
          "title": "Din leverans är på väg",
          "content": "Följ paketet i realtid eller välj en ny leveranstid.",
          "mediaUrl": "/media/2026-10-rcs-sms-fallback.webp",
          "height": "Medium"
        },
        "suggestions": [
          {
            "text": "Följ leveransen",
            "type": "OpenUrlAction",
            "url": "https://example.com"
          }
        ],
        "fallbackPolicy": "FallbackOnNoCapability,FallbackOnFailure",
        "fallbackMessage": "Ditt paket är på väg. Följ leveransen via example.com."
      }
    }
  ]
}