كيفية إرسال رسالة نصية من Kotlin

أبسط طريقة لإرسال رسائل SMS من Kotlin هي استخدام واجهة برمجة تطبيقات HTTP/Rest المدمجة لبوابة Ozeki SMS. عند استخدام هذه الواجهة، ستقوم بإرسال رسائل SMS عن طريق إصدار طلب HTTP Post إلى بوابة SMS. سيحتوي طلب HTTP Post على رسالة مُنسقة بتنسيق JSON. ستقوم بوابة SMS بإرسال هذه الرسالة إلى هاتف المستلم، وسيتم إرجاع استجابة HTTP 200 OK لطلبك. (الشكل 1)

كيفية إرسال رسالة نصية من kotlin
الشكل 1 - كيفية إرسال رسالة نصية من Kotlin

كود Kotlin لإرسال رسالة نصية إلى الهاتف المحمول

نموذج كود Kotlin لإرسال الرسائل النصية أدناه يوضح كيفية إرسال الرسائل النصية باستخدام واجهة برمجة تطبيقات REST لرسائل SMS الخاصة بـ Ozeki SMS Gateway باستخدام مكتبة Kotlin Ozeki.Libs.Rest. هذه المكتبة مقدمة لك مجانًا، ويمكنك استخدامها وتعديلها في أي من مشاريعك.

الفيديو 1 - كيفية تحميل مثال SendSms.kt.zip (برنامج تعليمي بالفيديو)

MainActivity.kt
package send.sms

import android.os.Build
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.text.method.ScrollingMovementMethod
import androidx.annotation.RequiresApi
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.GlobalScope
import kotlinx.coroutines.launch
import Ozeki.Libs.Rest.Configuration
import Ozeki.Libs.Rest.Message
import Ozeki.Libs.Rest.MessageApi

class MainActivity : AppCompatActivity() {
    @RequiresApi(Build.VERSION_CODES.O)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val btnSendRequest:android.widget.Button = findViewById(R.id.btnSendRequest)
        val inputToAddress:android.widget.EditText = findViewById(R.id.inputToAddress)
        val inputMessage:android.widget.EditText = findViewById(R.id.inputMessage)
        val logBox:android.widget.TextView = findViewById(R.id.logBox)
        logBox.movementMethod = ScrollingMovementMethod()

        val configuration = Configuration(
            username = "http_user",
            password = "qwe123",
            apiurl = "http://10.0.2.2:9509/api"
        )

        val api = MessageApi(configuration)

        btnSendRequest.setOnClickListener {
            if (inputToAddress.text.toString() != "" && inputMessage.text.toString() != "") {
                GlobalScope.launch(Dispatchers.IO) {
                    val msg = Message()
                    msg.ToAddress = inputToAddress.text.toString()
                    msg.Text = inputMessage.text.toString()
                    inputToAddress.text.clear()
                    inputMessage.text.clear()
                    val response = api.Send(msg)
                    logBox.text = String.format("%s\n%s", logBox.text, response.toString())
                }
            }
        }
    }
}
	
main_activity.xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="send.sms.MainActivity">

    <Button
        android:id="@+id/btnSendRequest"
        android:layout_width="320dp"
        android:layout_height="50dp"
        android:layout_marginBottom="24dp"
        android:text="إرسال"
        android:backgroundTint="#FF3F3F"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="0.505"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/logBox"
        app:layout_constraintVertical_bias="0.776" />

    <EditText
        android:id="@+id/inputMessage"
        android:layout_width="320dp"
        android:layout_height="150dp"
        android:layout_marginTop="32dp"
        android:ems="10"
        android:gravity="start|top"
        android:hint="مرحبًا بالعالم!"
        android:inputType="textMultiLine"
        android:textColorHint="#BFBFBF"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="0.494"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/textView" />

    <TextView
        android:id="@+id/textView"
        android:layout_width="320dp"
        android:layout_height="wrap_content"
        android:layout_marginTop="20dp"
        android:text="الرسالة:"
        android:textSize="20sp"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="0.505"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/inputToAddress" />

    <TextView
        android:id="@+id/textView2"
        android:layout_width="320dp"
        android:layout_height="wrap_content"
        android:layout_marginTop="40dp"
        android:text="عنوان المرسل إليه:"
        android:textSize="20sp"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="0.505"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <EditText
        android:id="@+id/inputToAddress"
        android:layout_width="320dp"
        android:layout_height="wrap_content"
        android:layout_marginTop="16dp"
        android:ems="10"
        android:hint="+36201111111"
        android:inputType="textPersonName"
        android:textColorHint="#BFBFBF"
        android:textSize="18sp"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="0.505"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/textView2" />

    <TextView
        android:id="@+id/logBox"
        android:layout_width="320dp"
        android:layout_height="160dp"
        android:layout_marginTop="36dp"
        android:scrollbars="vertical"
        android:text="السجل:"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="0.505"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/inputMessage" />

</androidx.constraintlayout.widget.ConstraintLayout>
	

كيفية استخدام مثال Kotlin لإرسال الرسائل النصية:

يمكنك استخدام فئة Message لإنشاء الرسالة النصية ويمكنك استخدام فئة MessageApi لإرسال الرسالة النصية إلى بوابة الرسائل النصية. ستقوم بوابة الرسائل النصية بإعادة توجيه رسالتك إلى شبكة الهاتف المحمول إما عبر اتصال لاسلكي أو عبر الإنترنت.

تنزيل SendSms.kt

يمكن تنزيل الكود المصدري المشرح في هذه المقالة واستخدامه وتعديله مجانًا.
تنزيل: SendSms.kt.zip (148 كيلوبايت)

ما الموجود في ملف SendSms.kt.zip؟

يحتوي ملف SendSms.kt.zip على مشروع المثال، والذي يتضمن مكتبة Ozeki.Libs.Rest. باستخدام هذه المكتبة، يمكنك إرسال وحذف وتمييز واستقبال رسائل SMS عن طريق إنشاء MessageApi واستخدام الطرق Send() وDelete() وMark() وReceive(). (الشكل 2)

مشروع مثال لإرسال رسائل SMS باستخدام Node.js
الشكل 2 - دليل SendSms.kt

كيفية إرسال رسائل SMS من Kotlin (خطوات سريعة)

لإرسال رسائل SMS من Kotlin:

  1. تثبيت Ozeki SMS Gateway
  2. ربط Ozeki SMS Gateway بشبكة الهاتف المحمول
  3. إرسال رسالة SMS تجريبية من واجهة Ozeki
  4. إنشاء مستخدم HTTP SMS API
  5. Android Studio
  6. تنزيل مشروع المثال أعلاه
  7. إنشاء الرسالة عن طريق إنشاء كائن Message جديد
  8. إنشاء API لإرسال رسالتك
  9. استخدام طريقة Send لإرسال رسالتك
  10. قراءة رسالة الاستجابة على وحدة التحكم
  11. فحص السجلات في بوابة الرسائل

تثبيت Ozeki SMS Gateway وإنشاء مستخدم HTTP API

لتتمكن من إرسال رسائل SMS من Kotlin، تحتاج أولاً إلى تثبيت Ozeki SMS Gateway. يمكن تثبيت بوابة الرسائل على نفس الكمبيوتر الذي تقوم فيه بتطوير كود Kotlin في Android Studio. بعد التثبيت، الخطوة التالية هي ربط Ozeki SMS Gateway بشبكة الهاتف المحمول. يمكنك إنشاء مستخدم HTTP SMS API. قم بإنشاء مستخدم باسم مستخدم "http_user" وكلمة مرور "qwe123" لجعل المثال يعمل دون تعديل.

بعد إعداد البيئة، يمكنك تشغيل كود Kotlin الخاص بك.

رابط HTTP API لإرسال رسائل SMS من Kotlin

لإرسال رسائل SMS من Kotlin، سيتعين على Kotlin إصدار طلب HTTP إلى بوابة الرسائل. يظهر رابط API أدناه. لاحظ أنه يجب استبدال عنوان IP (127.0.0.1) بعنوان IP الخاص ببوابة الرسائل. إذا كان Ozeki SMS Gateway مثبتًا على نفس الكمبيوتر الذي يعمل عليه تطبيق JavaScript SMS، فيمكن أن يكون هذا 127.0.0.1. إذا كان مثبتًا على كمبيوتر مختلف، فيجب أن يكون عنوان IP الخاص بهذا الكمبيوتر.

http://127.0.0.1:9509/api?action=rest
    

مصادقة HTTP لإرسال رسائل SMS من Kotlin

لمصادقة عميل SMS في Kotlin، تحتاج إلى إرسال اسم المستخدم وكلمة المرور في سلسلة مشفرة بـ base64 إلى الخادم في طلب HTTP. التنسيق المستخدم هو: base64(username+":"+password). في Kotlin يمكنك استخدام الكود التالي لإجراء هذا التشفير:

var usernamePassword = "%s:%s".format(username, password)
return "Basic %s".format(Base64.getEncoder().encodeToString(usernamePassword.toByteArray()))
    

على سبيل المثال، إذا قمت بتشفير اسم المستخدم 'http_user' وكلمة المرور 'qwe123'، فستحصل على السلسلة المشفرة بـ base64 التالية: aHR0cF91c2VyOnF3ZTEyMw==. للإرسال

رأس طلب HTTP لإرسال رسائل SMS من Kotlin

لإرسال رسائل SMS، تحتاج إلى تضمين الأسطر التالية كرؤوس في طلب HTTP. لاحظ أننا نضمن نوع المحتوى ورأس المصادقة.

Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    

طلب HTTP لإرسال رسائل SMS من Kotlin

لإرسال الرسالة، سيقوم تطبيق Kotlin الخاص بك بإرسال طلب HTTP مشابه للطلب أدناه. لاحظ أن هذا الطلب يتضمن جزءًا من رأس HTTP وجزءًا من جسم HTTP. جسم HTTP هو سلسلة بيانات مشفرة بـ JSON. يحتوي على رقم المستلم ونص الرسائل.

POST /api?action=sendmsg HTTP/1.1
Connection: Keep-Alive
Content-Length: 323
Content-Type: application/json; charset=utf-8
Accept-Encoding: gzip
Authorization: Basic aHR0cF91c2VyOnF3ZTEyMw==
Host: 10.0.2.2:9509
User-Agent: okhttp/4.2.2

{
    "messages":	[
        {
            "message_id":	"b686acf6-7420-4a3d-b444-779dcffc652b",
            "to_address":	"+36201111111",
            "text":	"Hello world!",
            "create_date":	"2021-06-17T09:48:30",
            "valid_until":	"2021-06-24T09:48:30",
            "time_to_send":	"-999999999-01-01T00:00",
            "submit_report_requested":	true,
            "delivery_report_requested":	true,
            "view_report_requested":	true
        }
    ]
}
    

استجابة HTTP المستلمة بواسطة مثال Kotlin للرسائل القصيرة

بمجرد أن يستقبل بوابة الرسائل القصيرة هذا الطلب، ستقوم بإنشاء استجابة HTTP. ستحتوي استجابة HTTP على رمز حالة، للإشارة إلى ما إذا كان طلب إرسال الرسالة القصيرة ناجحًا أم لا. كما ستعود أيضًا بهيكل مشفر بـ JSON لتزويدك بتفاصيل مفيدة حول إرسال الرسالة.

HTTP/1.1 200 OK
User-Agent: OZEKI 10.3.120 (www.myozeki.com)
Content-Type: application/json; charset=utf8
Last-Modified: Wed, 16 Jun 2021 09:06:03 GMT
Server: 10/10.3.120
Transfer-Encoding: chunked

{
	"http_code": 200,
	"response_code": "SUCCESS",
	"response_msg": "Messages queued for delivery.",
	"data": {
	  "total_count": 1,
	  "success_count": 1,
	  "failed_count": 0,
	  "messages": [
	    {
	      "message_id": "b686acf6-7420-4a3d-b444-779dcffc652b",
	      "from_station": "%",
	      "to_address": "+36201111111",
	      "to_station": "%",
	      "text": "Hello world!",
	      "create_date": "2021-06-17 09:48:30",
	      "valid_until": "2021-06-24 09:48:30",
	      "time_to_send": "2021-06-17 09:48:30",
	      "submit_report_requested": true,
	      "delivery_report_requested": true,
	      "view_report_requested": false,
	      "tags": [
	        {
	          "name": "Type",
	          "value": "SMS:TEXT"
	        }
	      ],
	      "status": "SUCCESS"
	    }
	  ]
	}
}
	

كيفية إرسال رسالة قصيرة من Kotlin باستخدام واجهة برمجة تطبيقات الرسائل القصيرة ومشروع المثال أعلاه (فيديو تعليمي)

يُظهر لك هذا الفيديو كيفية تنزيل واستخدام مشروع SendSms.kt. بمجرد فتحك لمشروع المثال، قد تلاحظ وجود حزمة تسمى Ozeki.Libs.Rest هذه هي الحزمة التي تحتوي على MessageApi وكل ما تحتاجه لإرسال رسالة قصيرة باستخدام Kotlin.

الفيديو 2 - كيفية إرسال رسالة قصيرة باستخدام كود Kotlin أعلاه (فيديو تعليمي)

كيفية التحقق من أن الرسالة القصيرة قد تم قبولها بواسطة مستخدم HTTP

بعد إرسال الرسالة القصيرة، من الجيد التحقق من بوابة الرسائل القصيرة الخاصة بك، لمعرفة ما استقبلته. يمكنك التحقق من السجل عن طريق فتح تفاصيل مستخدم HTTP من وحدة تحكم إدارة بوابة Ozeki للرسائل القصيرة. في نهاية الفيديو أعلاه يمكنك رؤية كيفية التحقق مما إذا كان الطلب قد تم استلامه بواسطة http_user. (الشكل 3)

kotlin project to send sms message
الشكل 3 - مشروع SendSms.kt في Android Studio

كيف تبدو التطبيق عند استخدامه

في الشكل 4، يمكنك رؤية كيف يبدو التطبيق بعد إرسال رسالة به. كما ترى، سيتم تخزين الرسائل التي أرسلتها سابقًا كـ سجل تحت مربع النص 'الرسالة'. يمكنك رؤية جميع المعلومات حول الرسالة مثل المرسل، النص، ونتيجة عملية الإرسال.

example kotlin application to send sms
الشكل 4 - تطبيق مثال SendSms قبل وبعد إرسال الرسالة

كيفية التحقق من أن الرسالة القصيرة قد تم إرسالها إلى شبكة الهاتف المحمول

الخطوة الأخيرة في التحقق من الإجراء هي إلقاء نظرة على سجلات اتصال شبكة الهاتف المحمول. قد تحتاج إلى تفعيل التسجيل في إعدادات الاتصال قبل إرسال الرسالة لرؤية السجلات. إذا تم تفعيل التسجيل، فسترى رقم الهاتف والنص الرسالة التي أرسلتها.

الفيديو 3 - كيفية اختبار ما إذا كان عميل SMPP قد استلم طلبنا (فيديو تعليمي)

كيفية إضافة Ozeki.Libs.Rest إلى مشروعك الخاص

يمكن تنزيل واستخدام وتعديل مكتبة Ozeki.Libs.Rest مجانًا.
تنزيل: Ozeki.Libs.Rest.kt.zip (7.66 كيلوبايت)

إذا قررت إنشاء تطبيقك بنفسك فقط باستخدام مكتبة Ozeki.Libs.Rest ، فهناك بعض الأشياء التي يجب تغييرها في تطبيقك الأساسي. لاستخدام مكتبة Ozeki.Libs.Rest، يجب وضعها في مجلد java للدليل الرئيسي
في الفيديو التالي، سأريك كيفية تنزيل وإضافة مكتبة Ozeki.Libs.Rest إلى مشروعك الخاص.

الفيديو 4 - كيفية إضافة مكتبة Ozeki.Libs.Rest إلى تطبيقك الخاص (فيديو تعليمي)

التبعيات

من المهم ذكر أن مكتبة Ozeki.Libs.Rest لديها بعض التبعيات. لاستخدامها، يجب إضافة هذه التبعيات إلى Gradle Scripts.

implementation "com.squareup.okhttp3:okhttp:4.2.2"
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.0'
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.0'
	

الكود 1 - قائمة التبعيات التي تحتاج إلى تضمينها.

إضافة التبعيات (فيديو تعليمي)

في الفيديو التالي، ستتعلم كيفية إضافة التبعيات المذكورة سابقًا. سيبدأ بنسخ الكود وسيأخذك خطوة بخطوة حتى إضافة التبعيات بنجاح. يبلغ طول الفيديو 53 ثانية فقط، لكنه يحتوي على جميع الخطوات اللازمة لإكمال العملية. يمكنك متابعة هذا البرنامج التعليمي دون أي جهد.

الفيديو 5 - كيفية إضافة التبعيات المطلوبة (فيديو تعليمي)

الوصول إلى الإنترنت

لتمكين تطبيقك من إرسال طلب HTTP، يجب عليك تمكين اتصال التطبيق بالإنترنت.
في الفيديو التالي، سأريكم كيفية تمكين الوصول إلى الإنترنت لتطبيق Kotlin الخاص بك.

<uses-permission android:name="android.permission.INTERNET" />
	

الكود 2 - لتمكين الوصول إلى الإنترنت لتطبيق Kotlin الخاص بك.

android:usesCleartextTraffic="true"
	

الكود 3 - لتمكين إرسال طلبات HTTP

كيفية تمكين اتصال الإنترنت لتطبيقك (فيديو تعليمي)

يجب عليك إضافة هذين السطرين إلى ملف AndroidManifest.xml.
في الفيديو التالي، سأريكم أين يجب وضع الأكواد أعلاه. سيبدأ الفيديو بنسخ الكود وسيأخذك حتى إضافة اتصال الإنترنت بنجاح. هذا الفيديو مفصل ويوفر وقتًا سهلًا لمتابعته.

الفيديو 6 - كيفية تمكين الوصول إلى الإنترنت لتطبيقك (فيديو تعليمي)

الختام

كان الغرض من هذا الدليل هو إظهار كيفية إرسال رسائل SMS من Kotlin باستخدام واجهة برمجة تطبيقات HTTP SMS لبوابة Ozeki SMS. المعرفة التي تعلمتها تمنحك القدرة على البقاء على اتصال مع عملائك باستخدام كود Kotlin بسيط. المراسلة الدولية ممكنة أيضًا مع بوابة Ozeki SMS، لأنها تعمل في أي دولة ويمكنها إرسال واستقبال الرسائل القصيرة عبر اتصالات متنوعة.

تأكد من مواصلة دراستك هنا، قم بزيارة صفحات تعليمية أخرى على موقع Ozeki للمزيد من المعلومات. تحقق من المزيد من الأدلة حول استخدام Kotlin، ابدأ بدليل كيفية إرسال رسائل SMS متعددة من Kotlin.

الآن أول شيء عليك فعله هو تنزيل بوابة Ozeki SMS والبدء في استخدامها!

More information