# Developer Guide

> **Source**: [SMS-Magic](https://docs.beconversive.com/6PuY9sqj0B8-developer-guide)

## Browse Collection

1. [Conversive Messaging API Document](https://docs.beconversive.com/6PuY9sqj0B8-developer-guide/gkeCPU60BwE-conversive-messaging-api-document.md) (Article)

---

# ARTICLE: Conversive Messaging API Document

## METADATA

- id: GclU1uxUVrtKgZh1w5KlPQ
- type: article
- source: SMS-Magic
- content_url: https://docs.beconversive.com/6PuY9sqj0B8-developer-guide/gkeCPU60BwE-conversive-messaging-api-document

- collection_url: https://docs.beconversive.com/6PuY9sqj0B8-developer-guide

## CONTENT

## Overview of the Conversive Messaging API Document

The Conversive Messaging API empowers businesses to optimize communication through SMS, offering robust features for sending messages, tracking delivery statuses, and managing messaging workflows efficiently. Built for flexibility and scalability, the API integrates seamlessly with existing systems, enhancing customer engagement and streamlining operations.

### Key Features

1. **Plain Text Message**

- Send individual plain text SMS messages to your audience.
- Refer: [https://www.postman.com/conversive/conversive-messaging-api/request/hdxg3kj/plain-text-message](https://www.postman.com/conversive/conversive-messaging-api/request/hdxg3kj/plain-text-message)
2. **Bulk Text Message**

- Send plain text SMS messages in bulk to multiple recipients simultaneously.
- Refer: [https://www.postman.com/conversive/conversive-messaging-api/request/ifdylfr/bulk-text-message](https://www.postman.com/conversive/conversive-messaging-api/request/ifdylfr/bulk-text-message)
3. **Get Balance:**

- Retrieve the remaining SMS credit balance for your SMS Magic account.
- Refer: [https://www.postman.com/conversive/conversive-messaging-api/request/u8p8lzp/get-balance](https://www.postman.com/conversive/conversive-messaging-api/request/u8p8lzp/get-balance)
4. **Tracking Delivery Status:**

- Configure Incoming & Delivery Push URLs in the Conversive portal. This ensures incoming SMS and delivery reports are pushed to the specified URLs for seamless tracking.

## **Base URL**

[https://api.beconversive.com](https://api.beconversive.com)

## **Authentication**

All requests must include a valid API key in the userPayload.apiKey field of the request body.

**Headers:**

**Key**

**Value**

Content-Type

application/json

---

## **Endpoint: Send Plain Text SMS**

**Method:**

POST /api/v2/message/send

**Request Parameters:**

**Parameter**

**Type**

**Required**

**Description**

userPayload.type

string

Yes

Always set to *api*.

userPayload.apiKey

string

Yes

The API key for authentication.

messageDetails

array

Yes

A list of messages to send. Each message contains:

messageDetails.soure

strig

Yes

The source number for sending the SMS. Must be 8001.

messageDetails.sendr

object

Yes

Details about the sender. Contains phone and channelType.

messageDetails.recipient

array

Yes

Details about the recipient(s). Contains phone and channelType.

messageDetails.messageId

string

No

A unique identifier for the message (optional).

messageDetails.message

string

Yes

The message content. Contains type and content.messageText.

**Example Request:**

```
POST https://api.beconversive.com/api/v2/message/send
Content-Type: application/json

{
   "userPayload": {
       "type": "api",
       "apiKey": "12345-abcde-67890-fghij"
   },
   "messageDetails": [
       {
           "source": "8001",
           "sender": {
               "phone": "+11234567890",
               "channelType": "SMS"
           },
           "recipient": [
               {
                   "phone": "+19876543210",
                   "channelType": "SMS"
               }
           ],
           "messageId": "test123",
           "message": {
               "type": "text",
               "content": {
                   "messageText": "Hello! This is a test message."
               }
           }
       }
   ]
}```

---

### **Responses**

**Successful Response**

```
{
   "response": {
       "vstatus": "success",
       "responseText": "Request(s) queued successfully."
   }
}```

**Error Responses**

```
{
   "response": {
       "vstatus": "failed",
       "responseText": "FORBIDDEN-API-KEY"
   }
}```

---

### **Notes**

1. **Source**: The source parameter must always be set to 8001.
2. **Sender Channel Type**: Must always be set to SMS.
3. **Recipient Channel Type**: Must always be set to SMS.
4. **Message Content**: For text messages, use "type": "text" and include the message in content.messageText.
5. **Authentication**: Replace <API_KEY> with your actual API key in the userPayload.apiKey field.
6. **Postman collection : ****[https://www.postman.com/conversive/conversive-messaging-api/overview](https://www.postman.com/conversive/conversive-messaging-api/overview)**

---

## Tracking Delivery Status:

**Configure Incoming & Delivery Push URL from Conversive portal and for individual accounts**

### 
**Incoming Number Configuration from Conversive Portal:**

Follow the given procedure to assign Incoming number to your account from the Conversive portal.

1. Log in to the Conversive portal.
2. On the navigation bar Sender IDs.
*[Image]*
3. On the Sender IDs page, click on 3 dots in front of number.
4. Click on 'View Details'. 
*[Image]*
5. The Incoming Sender ID Details pop up appears.
*[Image]*
6. Under Incoming Configuration, click 'Add Push URL'. A blank text area appears.
7. Insert any URL to which you want to push your incoming text.
(e.g. [http://api.webhookinbox.com/i/fcL3J7dy/in/)](http://api.webhookinbox.com/i/fcL3J7dy/in/))
*[Image]*
8. Click Save. All Incoming SMS received on the Conversive Portal, is pushed to the assigned URL.
9. The Push to URL status is shown under Message History on Conversive Portal as shown in screen below.
*[Image]*
10. A sample Push Incoming SMS Request Payload is shown below:
*[Image]*

### 
**Delivery Configuration of Incoming Number for individual account:**

We can set Delivery report URL for Incoming Number per Account.
**Incoming Number:**

1. Assign Incoming number to your account from the admin portal.
2. Log in to the Conversive portal.
3. On the top menu bar, click SMS Services.
4. In the navigation pane on the right, under Incoming Numbers, click My Number.
5. On the My Number page that appears, select the country.
6. Click Details. The Incoming Number pop up appears.
*[Image]*
7. Under Delivery Configuration, click Add Push URL. The blank text area appears.
*[Image]*
8. Insert any URL to which you want to get the Delivery report. (e.g. [http://api.webhookinbox.com/i/fcL3J7dy/in/](http://api.webhookinbox.com/i/fcL3J7dy/in/)) All Delivery reports for outgoing messages on the Portal, are pushed to assigned URL.
A sample Push Delivery Report SMS Request Payload :
*[Image]*