Used to initiate a new dialog with a customer by sending the first message. Note: To send RCS to multiple recipients simultaneously, use the endpoint Bundles.
Start a new conversation #
Quick start #
Quick start (cURL)
Copy to clipboard
curl -X POST https://api.ip1.net/v3/conversations \
-H "Authorization: Bearer API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"brand": "My-Store-Inc",
"agent": "Customer Service",
"recipient": "46700123456",
"type": "Carousel",
"carousel": [
{
"title": "Summer Campaign 2026",
"content": "Get 20% off all sunglasses!",
"mediaUrl": "https://cdn.site.se/promo-sun.jpg",
"type": 1,
"order": 0
},
{
"title": "Summer Sale 2026",
"content": "Get 20% off all sunglasses!",
"mediaUrl": "https://cdn.site.se/promo-sun.jpg",
"type": 1,
"order": 2
},
],
"suggestions": [
{
"text": "View selection",
"type": 1,
"order": 0,
"url": "https://site.se/shop",
"postbackData": "shop_click"
},
{
"text": "Call the store",
"type": 4,
"order": 1,
"phoneNumber": "468123456",
"postbackData": "call_click"
}
]
}'"Call #
Endpoint: /conversations
Methodology: POST
Example of call data #
filename.js
Copy to clipboard
{
"brand": "Min-Butik-AB",
"agent": "Customer Service",
"recipient": "46700123456",
"type": "Carousel",
"carousel": [
{
"title": "Summer Sale 2026",
"content": "Get 20% off all sunglasses!",
"mediaUrl": "https://cdn.site.se/promo-sun.jpg",
"type": 1,
"order": 0
},
{
"title": "Summer Sale 2026",
"content": "Get 20% off all sunglasses!",
"mediaUrl": "https://cdn.site.se/promo-sun.jpg",
"type": 1,
"order": 2
},
],
"suggestions": [
{
"text": "View selection",
"type": 1,
"order": 0,
"url": "https://site.se/shop",
"postbackData": "shop_click"
},
{
"text": "Call the store",
"type": 4,
"order": 1,
"phoneNumber": "468123456",
"postbackData": "call_click"
}
]
}Fields for request data #
| Field name | Description of the project | Required | Type | Example |
| brand | Your brand name | Yes | string | "My Shop Ltd." |
| agent | Your agent's name | Yes | string | ”Customer service” |
| recipient | Recipient's number | Yes | Object | ”46700123456”: { ”name”: ”Kalle” } |
| content | The content of the message itself | Yes (Except when using Cards) | string | ”Hi {name}! Your order has now been shipped.” |
| type | Message in conversation type | Yes | string | ”Carousell” |
| carousel | A list of multiple cards that create a Carousel | Required if the type is ”Carousel” | Array | (See table below) |
| card | Contains image, headline, and text (Rich Card). | Required if the type is ”Card” | Object | (See table below) |
| suggestions | A list of interactive buttons. | No, it is not. | Array | (See table below) |
| uniqueId | Unique ID to avoid duplicates. | No, it is not. | string | ”order-12345-id” |
Field details card #
| Field name | Description of the project | Required | Type | Example |
|---|---|---|---|---|
| title | The heading displayed at the top of the card. | Yes | string | ”Spring Sale!” |
| content | The descriptive text on the card. | Yes | string | ”We are emptying the warehouse now.” |
| type | Card type (2 for Rich Card in carousel). | Yes | Integer | 2 |
| order | Order in which cards are shown | Required if the ”Carousel” type is used | Integer | 1 |
| mediaUrl | URL to image or video (public link). | No, it is not. | URI | ”https://site.se/image.jpg” |
Field details suggestions #
| Field name | Description of the project | Required | Type | Example |
|---|---|---|---|---|
| text | The text on the button. | Yes | string | ”Shop now” |
| type | Action type (2=URL, 5=Share Location, 6=Call). | Yes | Integer | 2 |
| order | Determines the order suggestions are displayed. | Yes, with more than one suggestion | Integer | ”2” |
| postbackData | The data you get back upon a click. | Yes | string | ”track_sale_click” |
| URL | Target URL (required for type 2). | No, it is not. | string | ”https://site.se/shop” |
| Title | Title for Show Location on Map and Calendar Event. | Required for types 5 and 3 | string | ”Our Store” |
| Description | Event description. | Required for Type 3 | string | ”Welcome for a haircut!” |
| Start Time | The start time for a calendar event. | Required for Type 3 | string | ”2026-07-01T14:30” |
| EndTime | The end time for a calendar event. | Required for Type 3 | string | ”2026-07-01T15:30” |
| Latitude | Latitude to display a location on a map. | Required at Type 5 | string | ”58.3944347” |
| Longitude | The longitude to display a location on a map. | Required at Type 5 | string | ”13.8601547,18” |
| PhoneNumber | The phone number being dialed when the button is pressed | Required at type 6 | string | ”46101606060” |
Responsibility #
Returns the first message in the created conversation.
Example of response data #
Response data (JSON)
Copy to clipboard
{
"id": "65eb3d14f1234567890abcdef",
"conversationId": "65e15d14f1234547890ghijkl",
"brand": "my-store-inc",
"agent": "customer-service"
"recipient": "46700123456",
"type": "Carousell",
"content": "Hello! How can we help you today?",
"card": {
"title": "Order #12345",
"content": "The package is expected to arrive tomorrow.",
"mediaUrl": "https://cdn.site.se/package.jpg",
"type": 1,
"height": 2
},
"suggestions": [
{
"text": "Track Package",
"type": 1,
"url": "https://frakt.se/track/123",
"postbackData": "track_click",
"order": 0
}
]
"modified": "2026-03-09T08:00:05Z",
"uniqueId": "conversation-12345-id"
}Fields for response data #
| Field name | Description of the project | Type | Example |
| id | Message ID to which the current conversation belongs | string | "65eb3d14f1234567890abcdef" |
| brand | Brand's internal name. | string | ”my-store-ab” |
| agent | The agent handling the conversation. | string | ”customer service” |
| conversationId | The current conversation ID | string | ”65e15d14f1234547890ghijkl” |
| recipient | Recipient's number | Object | ”46700123456”: { ”name”: ”Kalle” } |
| content | The first message in the conversation content | string | ”Hi! How can we help you today?” |
| type | The first message in the conversation type | string | ”Carousell” |
| modified | Timestamp of last modification (status update, response, etc.) | DateTime | ”2026-03-09T08:00:05Z” |
| uniqueId | Unique ID to avoid duplicates. | string | ”conversation-12345-id” |
Continue conversation #
Used to send additional messages in an ongoing conversation.
Quick start #
Quick start (cURL)
Copy to clipboard
curl -X POST https://api.ip1.net/v3/conversations/65e15d14f1234547890ghijkl \
-H "Authorization: Bearer API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "Here is the information you requested."}'Call #
Endpoint: /conversations/{conversation}
Methodology: GET
Example of call data #
Call (URL)
Copy to clipboard
https://api.ip1.net/v3/conversations/65e15d14f1234547890ghijklCall fields #
| Field name | Description of the project | Required | Type | Example |
| id | Conversation ID you wish to continue. | Yes | Query Parameter | 65e15d14f1234547890ghijkl |
Responsibility #
Returns details about the new message in the conversation.
Example of response data #
Response data (JSON)
Copy to clipboard
Hello! How can we help you today?Example of response data #
| Field name | Description of the project | Type | Example |
| id | New message ID | string | "65eb3d14f1234567890abcdef" |
| brand | Brand's internal name. | string | ”my-store-ab” |
| agent | The agent handling the conversation. | string | ”customer service” |
| conversationId | The current conversation ID | string | ”65e15d14f1234547890ghijkl” |
| recipient | Recipient's number | Object | ”46700123456”: { ”name”: ”Kalle” } |
| content | The new message's content | string | ”Hi! How can we help you today?” |
| type | New message type | string | ”Carousell” |
| modified | Last modified timestamp | DateTime | ”2026-03-09T08:00:05Z” |
| uniqueId | Unique ID to avoid duplicates. | string | ”conversation-12345-id” |