REST APIs

The REST APIs provide programmatic access to read and write Helpwise data. Create a new mailbox, read emails, fetch conversations, and more.

Overview

Below are some points that will help you get going with the REST APIs as quickly as possible.

  • Authenticating Requests
  • Rate Limiting
  • Pagination
  • Endpoints

Authenticating Requests

To make a REST API call, you must include request headers including the Authorization header with your API Key and API Key.

To get an API Key, you can visit helpwise's API credentials Page and click on Generate Credentials Page. Now You can copy your API Key and Secret pair from that page and use it to call our APIs.

Request Header Description
Authorization When you request an endpoint, send the value as the HTTP basic authentication credentials by using your api key and api secret.For example: Authorization: api key:api secret.If you use cURL, specify -u “api key:api secret”.Required.
Accept Set to application/json. Required.

Rate Limiting

HTTP Headers and Response Codes

Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.

Note that the HTTP headers are contextual. When using api key and api secret, they indicate the rate limit for the application context.

  • X-Rate-Limit-Limit:the rate limit ceiling for that given endpoint
  • X-Rate-Limit-Remaining:the number of requests left for the 1 hour window
  • X-Rate-Limit-Reset:the remaining window before the rate limit resets, in UTC epoch seconds

When an application exceeds the rate limit for a given API endpoint, the API will return a HTTP 429 “Too Many Requests” response code, along with a detailed error message in response body.

To better predict the rate limits available, consider periodically using GET application / rate_limit_status.

Pagination

Parameters for Pagination

  • limit (optional): The number of records to be returned. Default is 50. Maximum value for limit is 100.
  • page (optional): Page number to be returned. Defaults to 1.
  • offset (optional): The number of records to be returned. Default is 0. If provided with page it overrides the page number

When an application exceeds the limit i.e. greater than 100 for a given API endpoint, the API will return a HTTP 400 “Bad Request” response code, along with a detailed error message in response body.

Parameters needs to be provided in POST request in JSON.

Endpoints

We have endpoints for your mailboxes, emails, threads, users. We can also customize this data for your business or your own custom needs.

Mailboxes

This endpoint lets you create, list Mailboxes that you have on Helpwise. An example Mailbox object on Helpwise looks like this -

Sample Object


{
	"id":"204499"
	"displayName":"Helpwise Support"
	"email":"help@helpwise.io"
	"isVerified":true
	"forwardingAddress":"h.helpwise.io@email.helpwisemail.com"
}

Get Mailbox

You can use this endpoint, to get a single Mailbox on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/mailboxes/get

Parameters

Parameters Type Details
id (required) string Mailbox's id which is needed to be returned

Sample Request


    curl -X POST \
    -H "Accept: application/json" \
    -H "Authorization: {api key}:{api secret}" \
    --data '{
    "id":"204420"
}' \
--url  "https://app.helpwise.io/dev-apis/mailboxes/get"

Sample Response


    {
    "status": "success",
    "data": {
    "id": "204499",
    "forwardingAddress": "h.helpwise.io@email.helpiwsemail.com",
    "email": "help@helpwise.io",
    "isVerified": false,
    "displayName": "Helpwise Support",
    "stats": {
    "mine": 28,
    "unassigned": 395,
    "assigned": 50,
    "drafts": 3,
    "inbox": 194
    },
    "outboundSettings": {
    "active": "0",
    "settings": {
        "smtp": {
            "type": "2",
            "settings": {
                "servername": "smtp.helpwise.io",
                "username": "someusername",
                "port": "465",
                "security": "SSL",
                "password": "some password"
            }
        },
        "google": {
            "type": "1",
            "settings": {
                "isConnected": true,
                "email": "help@helpwise.io"
            }
        },
        "microsoft": {
            "type": "3",
            "settings": {
                "isConnected": false,
                "email": null
            }
        },
        "helpwise": {
            "type": "0",
            "settings": {
                "status": "inactive",
                "dns": {
                    "records": [
                        {
                            "host": "204499.helpwise.io",
                            "type": "CNAME",
                            "value": "email.helpwisemail.com",
                            "isValid": false
                        },
                        {
                            "host": "s1._domainkey.helpwise.io",
                            "type": "CNAME",
                            "value": "s1._domainkey.helpwisemail.com",
                            "isValid": false
                        },
                        {
                            "host": "s2._domainkey.helpwise.io",
                            "type": "CNAME",
                            "value": "s2._domainkey.helpwisemail.com",
                            "isValid": false
                        }
                    ],
                    "isValid": false
                }
            }
        }
    }
    }
    },
    "message": null
    }

Create Mailbox

You can use this endpoint, to create mailbox on Helpwise using your api key and api secret.

https://app.helpwise.io/dev-apis/mailboxes/create

Parameters

Parameters Type Details
displayName string Mailbox's name that you want to display Like for support@yourdomain.com We can have Yourdomain Support
email string email address associated with the mailbox

Sample Request


            curl -X POST \
            -H "Accept: application/json" \
            -H "Authorization: {api key}:{api secret}" \
            --data '{
              "email":"help@helpwise.io",
              "displayName": "Helpwise Support"
            }' \
            --url "https://app.helpwise.io/dev-apis/mailboxes/create"

Sample Response


    {
    "status":"success",
    "data":{
        {
        "id":"204499",
        "forwardingAddress":"h.helpwise.io@email.helpiwsemail.com",
        "email":"help@helpwise.io",
        "isVerified": true,
        "displayName": "Helpwise Support"
        }
    },
    "message": null
    }

List mailboxes

You can use this endpoint, to list your mailboxes on Helpwise using your api key and api secret. This api returns a paginated response that you can use to go through your mailboxes.

POST : https://app.helpwise.io/dev-apis/mailboxes/list

Parameters

Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"page":"1",
"limit":"20"
}' \
--url "https://app.helpwise.io/dev-apis/mailboxes/list"

Sample Response


    {
     "status":"success",
     "data":[
     {
      "id":"204499",
      "forwardingAddress":"h.helpwise.io@email.helpiwsemail.com",
      "email":"help@helpwise.io",
      "isVerified": true,
      "displayName": "Helpwise Support"
    },
    {
      "id":"204322",
      "forwardingAddress":"s.helpwise.io@email.helpiwsemail.com",
      "email":"s@helpwise.io",
      "isVerified": true,
      "displayName": "Helpwise Sales"
    }
  ],
  "message": null
   }

Conversations/Threads

This endpoint lets you create, list Conversations that you have on Helpwise. An example Thread object on Helpwise looks like this -

Sample Object


{
	"id": 229671,
	"totalEmailCount": 1,
	"tags": [],
	"isRead": true,
	"latestEmail": {
		"id": 232907,
		"snippet": "How Are you?",
		 "subject": "Hi, How are you. Regards, Crystel Rojo",
		 "to": {
			"help@helpwise.io": "Helpwise Support"
			},
		"from": {
		"crystel.rojo1212@gmail.com": "Crystel Rojo"
		},
		"hasAttachment": false,
		"date": "2019-11-19T03:31:57+0000",
		"inReplyTo": null,
		"snoozedAt": "2019-11-19T04:48:48+0000",
		"attachments": [],
		"labelID": 0,
	    "snoozedTill": "2019-11-19T06:42:00+0000"
		},
	 "hasDraft": false
}

Get emails of thread

You can use this endpoint, to get the all emails of threads on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/threads/get

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your email
thread_id (required) number thread_id of your mailbox

Sample Request



curl --location --request POST 'https://app.helpwise.io/dev-apis/threads/get' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
	"mailbox_id": 204568,
    "thread_id": 10933653
}'

Sample Response

List Threads

You can use this endpoint, to list your conversations on Helpwise using your api key and api secret. This api returns a paginated response that you can use to go through your mailboxes.

POST : https://app.helpwise.io/dev-apis/threads/list

Parameters

Parameters Type Details
mailboxId (required) number id of the mailbox for which you want to fetch the conversations.
labelId (optional) number The folder from which conversations need to be fetched. Defaults to 0(inbox).
tabType string mine, mention, all, assigned, unassigned, archive, spam, trash
tagId (optional) number Provide a tagId if you want to list conversations for a particular tag.
squery (optional) number Search query to perform a text based search on emails to list the search results.
Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


    curl -X POST \
    https://app.helpwise.io/dev-apis/threads/list \
    -H 'Accept: application/json' \
    -H 'Authorization: {api key}:{api secret}' \
    -d '{
    "limit":5,
    "page":1,
    "mailboxId":"204420"
}'

Sample Response


    {
    "status": "success",
    "data": [
        {
            "id": 252409,
            "totalEmailCount": 1,
            "tags": [],
            "isRead": true,
            "latestEmail": {
                "id": 233604,
                "snippet": "I've shared an item with you:\r\n\r\nTerms of Service\r\nhttps://docs.google.com/document/d/1tnf7P-YTvwyuZrN7iE029F0DaXHwkRH3CXYDCkSq-Uo/edit?usp=sharing&ts=5dd3c906\r\n\r\nIt's not an attachment -- it's st",
                "subject": "Terms of Service - Invitation to edit",
                "to": {
                    "vibhor@saaslabs.co": ""
                },
                "from": {
                    "drive-shares-noreply@google.com": "Prabhat Mishra (via Google Docs)"
                },
                "hasAttachment": false,
                "date": "2019-11-19T10:50:49+0000",
                "inReplyTo": null,
                "snoozedAt": null,
                "attachments": [],
                "labelID": 0,
                "snoozedTill": null
            },
            "hasDraft": false
        },
        {
            "id": 229671,
            "totalEmailCount": 1,
            "tags": [],
            "isRead": true,
            "latestEmail": {
                "id": 232907,
                "snippet": "SaaS Labs Inc:\r\n\r\nHere’s the latest activity across everything since  9am on Monday, November 18\r\n\r\n\r\n## SaaS Labs Inc HQ ##\r\n----------------------------------\r\n- 1 message was posted to the messag",
                "subject": "Basecamp (SaaS Labs Inc): Here’s the latest activity",
                "to": {
                    "vibhor@saaslabs.co": ""
                },
                "from": {
                    "notifications@3.basecamp.com": "Basecamp (SaaS Labs Inc)"
                },
                "hasAttachment": false,
                "date": "2019-11-19T03:31:57+0000",
                "inReplyTo": null,
                "snoozedAt": "2019-11-19T04:48:48+0000",
                "attachments": [],
                "labelID": 0,
                "snoozedTill": "2019-11-19T06:42:00+0000"
            },
            "hasDraft": false
        }
    ],
    "message": null
}

Assign Thread

You can use this endpoint, to assign the conversation to Helpwise's Users in Helpwise account using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/threads/assign

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your inbox
thread_id (required) number thread id of your inbox
assigned_to (required) number user id of your Helpwise account
assigned_to=0 number If you want to unassign the conversation

Sample Request

                                
curl --location --request POST 'https://app.helpwise.io/dev-apis/threads/assign' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mailbox_id": 204390,
    "thread_id": 53610037,
    "assigned_to":204377
}'

Sample Response


                            {
    "status": "success",
    "data": {
        "threadID": 53610037,
        "time": "2022-12-02T15:02:37+0000",
        "mailbox_id": 204390,
        "assigner": {
            "firstname": "Rishabh",
            "lastname": "Rawat",
            "fullname": "Rishabh Rawat",
            "id": 204377,
            "avatarTag": "RR",
            "isAvailable": "1",
            "email": "rishabh@helpwise.io",
            "role": "Account Owner"
        },
        "assigned": {
            "id": 204377,
            "email": "harit@helpwise.io",
            "firstname": "Harit",
            "lastname": "Dagar",
            "fullname": "Harit Dagar",
            "avatarTag": "HD",
            "avatarUrl": null,
            "isAvailable": null,
            "role": "Agent"
        },
        "conversation_link": "https://app.helpwise.io/mail/204390/inbox/53610037",
        "raw_text": "Rishabh Rawat assigned the converation to Harit Dagar"
    },
    "message": "Thread successfully assigned"
}

users

This endpoint lets you fetch users. An example User object on Helpwise looks like this -

Sample Object


{
	"id": 204378,
	"firstname": "Christel",
	"lastname": "Rojo",
	"email": "crystel.rojo@example.com"
}

Me

This is a special endpoint. You can use this endpoint, to get the authenticated user on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/users/me

Parameters

No Parameters are needed apart from Authentication Credentials

Sample Request


curl -X POST \
https://app.helpwise.io/dev-apis/users/me \
-H 'Accept: application/json' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: {api key}:{api secret}'

Sample Response


{
    "status": "success",
    "data": {
    "id": 204378,
    "firstname": "Christel",
    "lastname": "Rojo",
    "email": "crystel.rojo@example.com"
    },
    "message": null
}

List Users

You can use this endpoint, to get your all users in Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/users/list

Parameters

Parameters Type Details
mailbox_id (optional) if provided then you will get all users which having a inbox permission number mailbox id of your inbox

Sample Request

                                
curl --location --request POST 'https://app.helpwise.io/dev-apis/users/list' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mailbox_id":204390
}'

Sample Response


{
    "status": "success",
    "data": {
        "users": [
            {
                "id": 204377,
                "email": "rishabh@helpwise.io",
                "fullname": "Rishabh Rawat",
                "firstname": "Rishabh",
                "lastname": "Rawat",
                "avatarUrl": null,
                "avatarTag": "RR",
                "isAvailable": "1",
                "role": "Account Owner"
            }
        ]
    },
    "message": null
}

Notes

This endpoint lets you list Emails that you have on Helpwise. An example Email object on Helpwise looks like this -

Sample Object


                                    {
   "data":{
      "id":272645,
      "at":"2020-06-08T14:15:45+0000",
      "body":"\n
Hi Adam, please schedule a demo with this customer.<\/p><\/body><\/html>\n",
      "by":{
         "id":205571,
         "firstname":"Rishabh",
         "lastname":"Rawat",
         "email":"rishabh@helpwise.io",
         "avatarTag":"Avatar",
         "avatarUrl":"https:\/\/cdn.helpwise.io\/profile\/143d4b49e96f8725d317.1587616833.ae9baa2c550a4fd8c7cf"
      
},
      "attachments":[]
}
},

Add Note

You can use this endpoint, to add your notes on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/notes/add

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your email
thread_id (required) number thread_id of your mailbox
message string body of the note

Sample Request


curl --location --request POST 'https://app.helpwise.io/dev-apis/notes/add' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
	"mailbox_id":205234,
	"thread_id":1910985,
	"message":"Hi Rishabh! How may I help you?"
}'

Sample Response


                            {
    "status": "success",
    "data": {
        "comment": {
            "id": 272645
        }
    },
    "message": "Comment Added"
}

Emails

This endpoint lets you list Notes that you have on Helpwise. An example Notes object on Helpwise looks like this -

Sample Object


{
"id": 233604,
"cc": {},
"to": {
        "help@helpwise.io": "Helpwise Support"
	  },
"text": null,
"html": "You are invited to edit the google docs",
"subject": "Terms of Service - Invitation to edit",
"isSpam": false,
"from": {
		  "drive-shares-noreply@google.com": "Prabhat Mishra (via Google Docs)"
		},
"date": "2019-11-19T10:50:49+0000",
"sentBy": null,
"attachments": [],
"labelId": 0,
"inReplyTo": 204376,
"replyAll": false,
"forwardOf": null,
"readStats": {
               "readAt": [],
			   "distinctReadCount": null
			 },
"bcc": {}
}

List Emails

You can use this endpoint, to list your Emails in a particular Conversation on Helpwise using your api key and api secret. This api returns a paginated response that you can use to go through your mailboxes.

POST : https://app.helpwise.io/dev-apis/emails/list

Parameters

Parameters Type Details
mailboxId (required) number id of the mailbox for which you want to fetch the conversations.
threadId (required) number id of the thread for which you want to fetch the conversations.
Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


    curl -X POST \
    https://app.helpwise.io/dev-apis/emails/list \
    -H 'Accept: application/json' \
    -H 'Authorization: {api key}:{api secret}' \
    -d '{
    "limit":2,
    "page":1,
    "mailboxId":"204420",
    "threadId":"252409"
}'

Sample Response


	{
"status": "success",
"data": [
		{
			"id": 233604,
			"cc": {},
			"to": {
					"help@helpwise.io": "Helpwise Support"
				},
			"text": null,
			"html": '\n

                                

                                

                                

                            

                        

                        

                        

                        
prabhat@saaslabs.co
                        has invited you to edit the following document:
                    

                    

                

                









    
    



    
    
    



    
    
    



    
    
    











    
    
    



    
    
    



    
    
    







    Google Docs: Create and edit documents online. 
Google LLC, 1600 Amphitheatre Parkway, Mountain View, CA 94043,
    USA
 You have received this email because someone shared a document with you from Google Docs.		
    Logo for Google Docs



',
"subject": "Terms of Service - Invitation to edit",
"isSpam": false,
"from": {
"drive-shares-noreply@google.com": "Prabhat Mishra (via Google Docs)"
},
"date": "2019-11-19T10:50:49+0000",
"sentBy": null,
"attachments": [],
"labelId": 0,
"inReplyTo": 204376,
"replyAll": false,
"forwardOf": null,
"readStats": {
"readAt": [],
"distinctReadCount": null
},
"bcc": {}
}
],
"message": null
}

Send Email

You can use this endpoint, to send your email to your customer on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/emails/send_mail

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your email
to (required) string to email addresses of your customers(comma separated for multiple)
cc string cc email addresses of your customers(comma separated for multiple)
subject (required) string Subject of the email
email body (required) string Body of the email

Sample Request


curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"mailbox_id": 204811,
"to":"rishabh@saaslabs.co,rishabh@helpwise.io",
"cc":"help@helpwise.io",
"subject":"Balance your workload from Helpwise",
"body":""
}' \
--url "https://app.helpwise.io/dev-apis/emails/send_mail"

Sample Response


{
"status":"success",
 "data":null,
"message":"Email sent"
}

WhatsApp

This endpoint lets you send, list Messages that you have on Helpwise WhatsApp inbox. An example WhatsApp message thread Helpwise looks like this -

Sample Object


{
   "status":"success",
   "data":{
      "threads":[
         {
            "id":"918587805615",
            "totalSmsCount":1,
            "isRead":true,
            "last_message":"hello Rishabh, How may I help you?",
            "date":"2020-05-27T09:54:18+0000",
            "humanFriendlyDate":"27 May",
            "client_number":"918587805615",
            "your_number":"18304200005",
            "labelID":1,
            "tags":[
               {
                  "id":205223,
                  "name":"WhatsApp",
                  "color":"rgb(0, 255, 65)"

                }

          ]
},
   "message":null
}

WhatsApp Templates

You can use this endpoint, to get your all WhatsApp templates message in Helpwise account using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/whatsapp/templates/list

Parameters

Parameters Type Details
mailbox_id (required) number Inbox id of your WhatsApp Inbox

Sample Request


curl --location 'https://staging.app.helpwise.io/dev-apis/whatsapp/templates/list' \
--header 'Authorization: {api key}:{api secret}' \
--header 'Content-Type: application/json' \
--data '{
    "mailbox_id":221143
}'

Sample Response


                            {
    "status": "success",
    "data": [
        {
            "id": 204610,
            "body": "Hi {{1}}, \n Shipping updates. Your package order no {{2}} is under {{3}} and It should be delived at {{4}} date.\n\nHappy Shopping with us :)",
            "category": "SHIPPING_UPDATE",
            "language": "en_US",
            "name": "customer_shipping_status1",
            "namespace": "bc85d499_3431_4b51_b8f3_a307368a249b",
            "approved_status": true
        },
        {
            "id": 204611,
            "body": "Hi {{1}},\\n\\nWe have received your order no {{2}}. Please have a look and if you like our product then please leave a review for us.",
            "category": "ACCOUNT_UPDATE",
            "language": "en",
            "name": "customer_shipping_status2",
            "namespace": "bc85d499_3431_4b51_b8f3_a307368a249b",
            "approved_status": true
        }
    ],
    "message": null
}

Send WhatsApp Message

You can use this endpoint, to send your WhatsApp message to your customer on Helpwise using your api key and api secret. Note:- If you want to use the template message then message field is optional

POST : https://app.helpwise.io/dev-apis/whatsapp/send

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your email
to (required) number your customer
message string message of whatsapp
templateId (optional) number template id from template list API
template_variables_data (optional) array of string templates variable data

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
				-H "Authorization: {api key}:{api secret}" \
				--data '{
				"mailbox_id": 204811,
                "to":'+918587805615',
                "message":"Hello Rishabh, How are you?",
                "templateId":204610,
                "template_variables_data":["Rishabh","123","transit","23 Dec"]
			  }' \
			  --url "https://app.helpwise.io/dev-apis/whatsapp/send"

Sample Response


{
    "status": "success",
    "data": {
        "client_number": "+918587805615",
        "your_number": "+18304200005",
        "message_time": "2020-05-27T08:48:14+0000",
        "direction": "outbound-api",
        "delivery_status": "queued",
        "segments": "1",
        "body": "hello Rishabh",
        "sent_by": {
            "id": 205571,
            "firstname": "Helpwise",
            "lastname": "Team",
            "email": "help@helpwise.io"
        },
        "attachment": {},
        "id": 206658
    },
    "message": "Message sent"
}

List WhatsApp conversations

You can use this endpoint, to list the Helpwise WhatsApp conversations from your api key and api secret.

POST : https://app.helpwise.io/dev-apis/whatsapp/list

Parameters

Parameters Type Details
mailboxID (required) number mailbox id of your email
page number page no.
tabType string mine, mention, all, assigned, unassigned, archive, spam, trash

Sample Request


curl --location --request POST 'https://app.helpwise.io/dev-apis/sms/list' \
--header 'Authorization: {your_api_key}:{your_api_secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mailboxID": 205239,
    "page":1,
    "tabType":"all"
}'

Sample Response



{
"status": "success",
"data": {
    "threads": [
        {
            "id": 205404,
            "lastMsg": "Hello Rishabh",
            "date": "2021-06-01T09:05:38+0000",
            "humanFriendlyDate": "1 Jun",
            "clientNumber": "918587805615",
            "hwNumber": "14156349606",
            "tabType": "all",
            "tags": [
                {
                    "id": 247562,
                    "name": "WhatsApp",
                    "color": "rgb(241, 196, 15)"
                }
            ],
            "assignedTo": {
                "id": 205571,
                "firstname": "Peter",
                "lastname": "Johnson",
                "email": "help@helpwise.io",
                "profilePic": "https://cdn.helpwise.io/profile/143d4b49e96f8725d317.1587616833.ae9baa2c550a4fd8c7cf"
            },
            "contact": [ 
            {
                    "id": 818622,
                    "firstname": "Rishabh",
                    "lastname": "Rawat"
            }
            ],
            "isStarred": false,
            "isRead": true
        },
        {
            "id": 227056,
            "lastMsg": "Thank You ;)",
            "date": "2021-06-01T09:05:38+0000",
            "humanFriendlyDate": "1 Jun",
            "clientNumber": "919466966734",
            "hwNumber": "14156349606",
            "tabType": "all",
            "tags": [
                {
                    "id": 205223,
                    "name": "WhatsApp",
                    "color": "rgb(0, 255, 65)"
                },
                {
                    "id": 215580,
                    "name": "Premium Customer",
                    "color": "rgb(255, 61, 127)"
                }
            ],
            "assignedTo": {
                "id": 209546,
                "firstname": "Alice",
                "lastname": "M",
                "email": "alice@helpwise.io",
                "profilePic": null
            },
            "contact": [
                {
                    "id": 818622,
                    "firstname": "harit",
                    "lastname": ""
                }
            ],
            "isStarred": false,
            "isRead": true
        }
    ]
}
                        
}

List WhatsApp Messages

You can use this endpoint, to list the Helpwise WhatsApp Contact's Messages from your api key and api secret.

POST : https://app.helpwise.io/dev-apis/whatsapp/list

Parameters

Parameters Type Details
mailboxID (required) number mailbox id of your email
page number page no.
customerNumber number your customer's number

Sample Request


curl --location --request POST 'https://app.helpwise.io/dev-apis/whatsapp/messages' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
	"mailboxID": 205239,
    "page":2,
    "customerNumber":918587805615
}'

Sample Response



{
"status": "success",
"data": {
"sms": [
{
    "id": 717226,
    "hw_number": "14156349606",
    "client_number": "918587805615",
    "body": "Hi there",
    "message_time": "2021-04-05T12:12:23+0000",
    "delivery_status": "Delivered",
    "human_friendly_date": "5 Apr",
    "sent_by": {
        "id": 205571,
        "firstname": "Peter",
        "lastname": "Johnson",
        "email": "help@helpwise.io",
        "avatarUrl": "https://cdn.helpwise.io/profile/143d4b49e96f8725d317.1587616833.ae9baa2c550a4fd8c7cf"
    },
    "attachments": []
},
{
    "id": 665884,
    "hw_number": "14156349606",
    "client_number": "918587805615",
    "body": "hello",
    "message_time": "2021-03-22T05:42:10+0000",
    "delivery_status": "Delivered",
    "human_friendly_date": "22 Mar",
    "sent_by": {
        "id": 205571,
        "firstname": "Peter",
        "lastname": "Johnson",
        "email": "help@helpwise.io",
        "avatarUrl": "https://cdn.helpwise.io/profile/143d4b49e96f8725d317.1587616833.ae9baa2c550a4fd8c7cf"
    },
    "attachments": [
        {
            "id": 7485555,
            "media_url": "https://helpwisemail.s3-us-west-1.amazonaws.com/d41f188b7a2b40f75c1bbdb3349c546c60582d8e45abb1616391566.png",
            "content_type": "image/png",
            "filename": "IMG_6675.jpg",
            "filesize": "622390"
        }
    ]
}
]
},
"message": null
}

SMS

This endpoint lets you send, list SMS Messages that you have on Helpwise SMS inbox. An example SMS message thread Helpwise looks like this -

Sample Object


{
"status":"success",
"data":{
    "threads":[
        {
        "id":"918587805615",
        "totalSmsCount":1,
        "isRead":true,
        "last_message":"hello Rishabh, How may I help you?",
        "date":"2020-05-27T09:54:18+0000",
        "humanFriendlyDate":"27 May",
        "client_number":"918587805615",
        "your_number":"18304200005",
        "labelID":1,
        "tags":[
            {
                "id":205223,
                "name":"SMS",
                "color":"rgb(0, 255, 65)"

            }

        ]
},
"message":null
}

Send SMS

You can use this endpoint, to send your SMS message to your customer on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/sms/send

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your email
to (required) number your customer
message string message of SMS

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
				-H "Authorization: {api key}:{api secret}" \
				--data '{
				"mailbox_id": 204811,
                "to":'+918587805615',
                "message":"Hello Rishabh, How are you?"
			  }' \
			  --url "https://app.helpwise.io/dev-apis/sms/send"

Sample Response


{
"status": "success",
"data": {
    "client_number": "+918587805615",
    "your_number": "+18304200005",
    "message_time": "2020-05-27T08:48:14+0000",
    "direction": "outbound-api",
    "delivery_status": "queued",
    "segments": "1",
    "body": "Hello Rishabh, How are you?",
    "sent_by": {
        "id": 205571,
        "firstname": "Helpwise",
        "lastname": "Team",
        "email": "help@helpwise.io"
    },
    "attachment": [],
    "id": 206658
},
"message": "SMS sent"
}

List SMS conversations

You can use this endpoint, to list the Helpwise SMS conversations from your api key and api secret.

POST : https://app.helpwise.io/dev-apis/sms/list

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your email
page number page no.
tabType string mine, mention, all, assigned, unassigned, archive, spam, trash

Sample Request


curl --location --request POST 'https://app.helpwise.io/dev-apis/sms/list' \
--header 'Authorization: {your_api_key}:{your_api_secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mailboxID": 205239,
    "page":1,
    "tabType":"all"
}'

Sample Response



{
"status": "success",
"data": {
    "threads": [
        {
            "id": 205404,
            "lastMsg": "Hello Rishabh",
            "date": "2021-06-01T09:05:38+0000",
            "humanFriendlyDate": "1 Jun",
            "clientNumber": "918587805615",
            "hwNumber": "14156349606",
            "tabType": "all",
            "tags": [
                {
                    "id": 247562,
                    "name": "WhatsApp",
                    "color": "rgb(241, 196, 15)"
                }
            ],
            "assignedTo": {
                "id": 205571,
                "firstname": "Peter",
                "lastname": "Johnson",
                "email": "help@helpwise.io",
                "profilePic": "https://cdn.helpwise.io/profile/143d4b49e96f8725d317.1587616833.ae9baa2c550a4fd8c7cf"
            },
            "contact": [ 
            {
                    "id": 818622,
                    "firstname": "Rishabh",
                    "lastname": "Rawat"
            }
            ],
            "isStarred": false,
            "isRead": true
        },
        {
            "id": 227056,
            "lastMsg": "Thank You ;)",
            "date": "2021-06-01T09:05:38+0000",
            "humanFriendlyDate": "1 Jun",
            "clientNumber": "919466966734",
            "hwNumber": "14156349606",
            "tabType": "all",
            "tags": [
                {
                    "id": 205223,
                    "name": "WhatsApp",
                    "color": "rgb(0, 255, 65)"
                },
                {
                    "id": 215580,
                    "name": "Premium Customer",
                    "color": "rgb(255, 61, 127)"
                }
            ],
            "assignedTo": {
                "id": 209546,
                "firstname": "Alice",
                "lastname": "M",
                "email": "alice@helpwise.io",
                "profilePic": null
            },
            "contact": [
                {
                    "id": 818622,
                    "firstname": "harit",
                    "lastname": ""
                }
            ],
            "isStarred": false,
            "isRead": true
        }
    ]
}
                        
}

List SMS Messages

You can use this endpoint, to list the Helpwise SMS Contact's Messages from your api key and api secret.

POST : https://app.helpwise.io/dev-apis/sms/list

Parameters

Parameters Type Details
mailboxID (required) number mailbox id of your email
page number page no.
customerNumber number your customer's number

Sample Request


curl --location --request POST 'https://app.helpwise.io/dev-apis/sms/messages' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
	"mailboxID": 205239,
    "page":2,
    "customerNumber":918587805615
}'

Sample Response



{
"status": "success",
"data": {
    "sms": [
    {
        "id": 783776,
        "hw_number": "18304200005",
        "client_number": "918587805615",
        "body": "Hello Rishabh, we got your response. Please wait for our customer support Rishabh Rawat ",
        "message_time": "2021-04-20T12:41:28+0000",
        "delivery_status": "Read",
        "human_friendly_date": "20 Apr",
        "sent_by": {
            "id": 0,
            "firstname": "WhatsApp",
            "lastname": "Bot",
            "email": "whatsapp_bot@helpwise.io",
            "first_name": "WhatsApp",
            "last_name": "Bot",
            "avatarUrl": null
        },
        "attachment": {}
    }
        ]
    },
    "message": null
}

Chat Widget

This endpoint use to send chat widget messages that you have on Helpwise Chat inbox.

Send Chat Widget Message

You can use this endpoint, to send your chat widget message to your customer on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/chat/send

Parameters

Parameters Type Details
mailbox_id (required) number mailbox id of your chat widget inbox
thread_id (required) number when customer send you a message then helpwise will create thread id automatically(You will get this from webhook)
message string message of chat

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
				-H "Authorization: {api key}:{api secret}" \
				--data '{
				"mailbox_id": 204811,
                "thread_id":'494141',
                "message":"Hello Rishabh, How are you?"  // you can also send HTML text
			  }' \
			  --url "https://app.helpwise.io/dev-apis/chat/send"

Sample Response



{
 "status": "success",
    "data": {
        "thread_id": 494141,
        "mailbox_id": 204811,
        "contact_id": 5384617,
        "message_time": "2021-09-21T12:14:44+0000",
        "body": "Hello Rishabh, How are you?", // You will get the HTML text always
        "type": 0,
        "delivery_status": "Sent",
        "sent_by": {
            "id": 204767,
            "firstname": "Rishabh",
            "lastname": "Rawat",
            "email": "rishabh@saaslabs.co"
        },
        "attachment": [],
        "message_id": 851617
    },
    "message": "message sent"
}

Contacts

This endpoint lets you create, list contacts that you have on Helpwise. An example Contact object on Helpwise looks like this -

Sample Object


{
	"firstname": "Basecamp",
	"lastname": "Inc",
	"primaryEmail": "notifications@3.basecamp.com",
	"secondaryEmails": [
		"basecamp@gmail.com",
		"basecamp@outlook.com"
	],
	"phones": [
		{
		  "phoneNo": "919200000016",
		  "type": "9"
		},
		{
		  "phoneNo": "819090909090",
		  "type": "8"
		}
		      ],
	"id": 204811,
    "companyName": "Basecamp",
    "jobTitle": "Software Developer"
}

Get Contact

You can use this endpoint, to get your specific contact on Helpwise using your api key and api secret.

POST : https://app.helpwise.io/dev-apis/contacts/get

Parameters

Parameters Type Details
id (required) string Contacts's id

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
				-H "Authorization: {api key}:{api secret}" \
				--data '{
				"id": 204811,
			  }' \
			  --url "https://app.helpwise.io/dev-apis/contacts/get"

Sample Response


   {
	"firstname": "Basecamp",
	"lastname": "Inc",
	"primaryEmail": "notifications@3.basecamp.com",
	"secondaryEmails": [
		"basecamp@gmail.com",
		"basecamp@outlook.com"
	],
	"phones": [
		{
		  "phoneNo": "919200000016",
		  "type": "9"
		},
		{
		  "phoneNo": "819090909090",
		  "type": "8"
		}
	],
	"id": 204811,
    "companyName": "Basecamp",
    "jobTitle": "Software Developer"
}

List Contacts

You can use this endpoint, to fetch all your contacts on Helpwise

POST : https://app.helpwise.io/dev-apis/contacts/list

Parameters

Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
				-H "Authorization: {api key}:{api secret}" \
			  --url "https://app.helpwise.io/dev-apis/contacts/list"

Sample Response

                                                    
{
    "status": "success",
    "data": [
    {
        "id": 205361,
        "firstname": "Intercom",
        "lastname": "",
        "primaryEmail": "noreply@intercom.io",
        "secondaryEmails": [],
        "phones": []
    },
    {
        "id": 205072,
        "firstname": "",
        "lastname": "",
        "primaryEmail": "rishabh@helpwise.io",
        "secondaryEmails": [],
        "phones": []
    }
],
    "message": null
}

Search Contacts

You can use this endpoint, to fetch all your contacts on Helpwise

POST : https://app.helpwise.io/dev-apis/contacts/search

Parameters

Parameters Type Details
name (optional)^^ string Contacts's first name that you want to save
phone (optional)^^ string Phone No to look for
email (optional)^^ string Email to look for

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

^^One of the fields name,phone or email is required

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
                -H "Authorization: {api key}:{api secret}" \
                -d
			  --url "https://app.helpwise.io/dev-apis/contacts/search"

Sample Response

                                                    
{
    "status": "success",
    "data": [
    {
        "id": 205361,
        "firstname": "Intercom",
        "lastname": "",
        "primaryEmail": "noreply@intercom.io",
        "secondaryEmails": [],
        "phones": []
    },
    {
        "id": 205072,
        "firstname": "",
        "lastname": "",
        "primaryEmail": "rishabh@helpwise.io",
        "secondaryEmails": [],
        "phones": []
    }
],
    "message": null
}

Create Contact

You can use this endpoint, to create contacts on Helpwise using your api key and api secret.

https://app.helpwise.io/dev-apis/contacts/create

Parameters

Parameters Type Details
firstname (required) string Contacts's first name that you want to save
lastname (optional) string Contacts's last name that you want to save
emails (required) array Contact's emails addresses associated with your customer contacts. Pass an array of emails.
phones (optional) Object Contacts's phones no. Type define the which type of phone no you save. Pass an array of phones no.
companyName (optional) string Contacts's company name where he/she works
Job title (optional) string Contacts's job title

Sample Request


curl -X POST \
  -H "Accept: application/json" \
  -H "Authorization: {api key}:{api secret}" \
  --data '{
	        "firstname": "Rishabh",
	        "lastname": "Rawat",
	        "companyName": "Saas Labs",
	        "jobTitle": "Full Stack Web Developer",
	        "emails": ["rishabh@saaslabs.co","rishabh@helpwise.io"],
	        "phones": [
		      {
		          "phone": "8587805615",
		          "type": "1"
		      },
		      {
		          "phone": "7777878765",
		          "type": "2"
		       }
		       ]
		}'
--url "https://app.helpwise.io/dev-apis/contacts/create"

Sample Response


{
	"status":"success",
	"data":null,
	"message":"Contact saved successfully"
}